feat: add ability to handle voice events

This commit aims to add functionality for developers to create their own
voice receiver features that deal with events regarding Discord voice
channels.

It is implemented here since we need to handle such events for
the purposes of dynamically creating and deleting voice channels on
demand when guild members perform actions involving them, like
connecting, disconnecting, or moving between them.

Author: christolis

application/src/main/java/org/togetherjava/tjbot/config/Config.java

@@ -46,6 +46,7 @@ public final class Config {
     private final RSSFeedsConfig rssFeedsConfig;
     private final String selectRolesChannelPattern;
     private final String memberCountCategoryPattern;
+    private final List<String> dynamicVoiceChannelPatterns;
 
     @SuppressWarnings("ConstructorWithTooManyParameters")
     @JsonCreator(mode = JsonCreator.Mode.PROPERTIES)
@@ -94,7 +95,9 @@ private Config(@JsonProperty(value = "token", required = true) String token,
                     required = true) FeatureBlacklistConfig featureBlacklistConfig,
             @JsonProperty(value = "rssConfig", required = true) RSSFeedsConfig rssFeedsConfig,
             @JsonProperty(value = "selectRolesChannelPattern",
-                    required = true) String selectRolesChannelPattern) {
+                    required = true) String selectRolesChannelPattern,
+            @JsonProperty(value = "dynamicVoiceChannelPattern",
+                    required = true) List<String> dynamicVoiceChannelPatterns) {
         this.token = Objects.requireNonNull(token);
         this.githubApiKey = Objects.requireNonNull(githubApiKey);
         this.databasePath = Objects.requireNonNull(databasePath);
@@ -127,6 +130,7 @@ private Config(@JsonProperty(value = "token", required = true) String token,
         this.featureBlacklistConfig = Objects.requireNonNull(featureBlacklistConfig);
         this.rssFeedsConfig = Objects.requireNonNull(rssFeedsConfig);
         this.selectRolesChannelPattern = Objects.requireNonNull(selectRolesChannelPattern);
+        this.dynamicVoiceChannelPatterns = Objects.requireNonNull(dynamicVoiceChannelPatterns);
     }
 
     /**
@@ -418,4 +422,14 @@ public String getMemberCountCategoryPattern() {
     public RSSFeedsConfig getRSSFeedsConfig() {
         return rssFeedsConfig;
     }
+
+    /**
+     * Gets the list of voice channel patterns that are treated dynamically.
+     *
+     * @return the list of dynamic voice channel patterns
+     */
+    public List<String> getDynamicVoiceChannelPatterns() {
+        return this.dynamicVoiceChannelPatterns;
+    }
+
 }

application/src/main/java/org/togetherjava/tjbot/features/Features.java

@@ -20,6 +20,7 @@
 import org.togetherjava.tjbot.features.code.CodeMessageAutoDetection;
 import org.togetherjava.tjbot.features.code.CodeMessageHandler;
 import org.togetherjava.tjbot.features.code.CodeMessageManualDetection;
+import org.togetherjava.tjbot.features.dynamicvc.DynamicVoiceListener;
 import org.togetherjava.tjbot.features.filesharing.FileSharingMessageListener;
 import org.togetherjava.tjbot.features.github.GitHubCommand;
 import org.togetherjava.tjbot.features.github.GitHubReference;
@@ -146,6 +147,9 @@ public static Collection<Feature> createFeatures(JDA jda, Database database, Con
         features.add(new SlashCommandEducator());
         features.add(new PinnedNotificationRemover(config));
 
+        // Voice receivers
+        features.add(new DynamicVoiceListener());
+
         // Event receivers
         features.add(new RejoinModerationRoleListener(actionsStore, config));
         features.add(new GuildLeaveCloseThreadListener(config));

application/src/main/java/org/togetherjava/tjbot/features/VoiceReceiver.java

@@ -0,0 +1,69 @@
+package org.togetherjava.tjbot.features;
+
+import net.dv8tion.jda.api.events.guild.voice.GuildVoiceDeafenEvent;
+import net.dv8tion.jda.api.events.guild.voice.GuildVoiceMuteEvent;
+import net.dv8tion.jda.api.events.guild.voice.GuildVoiceStreamEvent;
+import net.dv8tion.jda.api.events.guild.voice.GuildVoiceUpdateEvent;
+import net.dv8tion.jda.api.events.guild.voice.GuildVoiceVideoEvent;
+
+import java.util.regex.Pattern;
+
+/**
+ * Receives incoming Discord guild events from voice channels matching a given pattern.
+ * <p>
+ * All voice receivers have to implement this interface. For convenience, there is a
+ * {@link VoiceReceiverAdapter} available that implemented most methods already. A new receiver can
+ * then be registered by adding it to {@link Features}.
+ * <p>
+ * <p>
+ * After registration, the system will notify a receiver whenever a new event was sent or an
+ * existing event was updated in any channel matching the {@link #getChannelNamePattern()} the bot
+ * is added to.
+ */
+public interface VoiceReceiver extends Feature {
+    /**
+     * Retrieves the pattern matching the names of channels of which this receiver is interested in
+     * receiving sent messages from. Called by the core system once during the startup in order to
+     * register the receiver accordingly.
+     * <p>
+     * Changes on the pattern returned by this method afterwards will not be picked up.
+     *
+     * @return the pattern matching the names of relevant channels
+     */
+    Pattern getChannelNamePattern();
+
+    /**
+     * Triggered by the core system whenever a member joined, left or moved voice channels.
+     *
+     * @param event the event that triggered this
+     */
+    void onVoiceUpdate(GuildVoiceUpdateEvent event);
+
+    /**
+     * Triggered by the core system whenever a member toggled their camera in a voice channel.
+     *
+     * @param event the event that triggered this
+     */
+    void onVideoToggle(GuildVoiceVideoEvent event);
+
+    /**
+     * Triggered by the core system whenever a member started or stopped a stream.
+     *
+     * @param event the event that triggered this
+     */
+    void onStreamToggle(GuildVoiceStreamEvent event);
+
+    /**
+     * Triggered by the core system whenever a member toggled their mute status.
+     *
+     * @param event the event that triggered this
+     */
+    void onMuteToggle(GuildVoiceMuteEvent event);
+
+    /**
+     * Triggered by the core system whenever a member toggled their deafened status.
+     *
+     * @param event the event that triggered this
+     */
+    void onDeafenToggle(GuildVoiceDeafenEvent event);
+}

application/src/main/java/org/togetherjava/tjbot/features/VoiceReceiverAdapter.java

@@ -0,0 +1,52 @@
+package org.togetherjava.tjbot.features;
+
+import net.dv8tion.jda.api.events.guild.voice.GuildVoiceDeafenEvent;
+import net.dv8tion.jda.api.events.guild.voice.GuildVoiceMuteEvent;
+import net.dv8tion.jda.api.events.guild.voice.GuildVoiceStreamEvent;
+import net.dv8tion.jda.api.events.guild.voice.GuildVoiceUpdateEvent;
+import net.dv8tion.jda.api.events.guild.voice.GuildVoiceVideoEvent;
+
+import java.util.regex.Pattern;
+
+public class VoiceReceiverAdapter implements VoiceReceiver {
+
+    private final Pattern channelNamePattern;
+
+    protected VoiceReceiverAdapter() {
+        this(Pattern.compile(".*"));
+    }
+
+    protected VoiceReceiverAdapter(Pattern channelNamePattern) {
+        this.channelNamePattern = channelNamePattern;
+    }
+
+    @Override
+    public Pattern getChannelNamePattern() {
+        return channelNamePattern;
+    }
+
+    @Override
+    public void onVoiceUpdate(GuildVoiceUpdateEvent event) {
+        // Adapter does not react by default, subclasses may change this behavior
+    }
+
+    @Override
+    public void onVideoToggle(GuildVoiceVideoEvent event) {
+        // Adapter does not react by default, subclasses may change this behavior
+    }
+
+    @Override
+    public void onStreamToggle(GuildVoiceStreamEvent event) {
+        // Adapter does not react by default, subclasses may change this behavior
+    }
+
+    @Override
+    public void onMuteToggle(GuildVoiceMuteEvent event) {
+        // Adapter does not react by default, subclasses may change this behavior
+    }
+
+    @Override
+    public void onDeafenToggle(GuildVoiceDeafenEvent event) {
+        // Adapter does not react by default, subclasses may change this behavior
+    }
+}

application/src/main/java/org/togetherjava/tjbot/features/dynamicvc/DynamicVoiceListener.java

@@ -0,0 +1,14 @@
+package org.togetherjava.tjbot.features.dynamicvc;
+
+import net.dv8tion.jda.api.events.guild.voice.GuildVoiceUpdateEvent;
+import org.jetbrains.annotations.NotNull;
+
+import org.togetherjava.tjbot.features.VoiceReceiverAdapter;
+
+public class DynamicVoiceListener extends VoiceReceiverAdapter {
+
+    @Override
+    public void onVoiceUpdate(@NotNull GuildVoiceUpdateEvent event) {
+        // TODO: Complete
+    }
+}

application/src/main/java/org/togetherjava/tjbot/features/system/BotCore.java

@@ -2,6 +2,12 @@
 
 import net.dv8tion.jda.api.JDA;
 import net.dv8tion.jda.api.entities.channel.Channel;
+import net.dv8tion.jda.api.entities.channel.unions.AudioChannelUnion;
+import net.dv8tion.jda.api.events.guild.voice.GuildVoiceDeafenEvent;
+import net.dv8tion.jda.api.events.guild.voice.GuildVoiceMuteEvent;
+import net.dv8tion.jda.api.events.guild.voice.GuildVoiceStreamEvent;
+import net.dv8tion.jda.api.events.guild.voice.GuildVoiceUpdateEvent;
+import net.dv8tion.jda.api.events.guild.voice.GuildVoiceVideoEvent;
 import net.dv8tion.jda.api.events.interaction.ModalInteractionEvent;
 import net.dv8tion.jda.api.events.interaction.command.CommandAutoCompleteInteractionEvent;
 import net.dv8tion.jda.api.events.interaction.command.MessageContextInteractionEvent;
@@ -16,6 +22,8 @@
 import net.dv8tion.jda.api.hooks.ListenerAdapter;
 import net.dv8tion.jda.api.interactions.callbacks.IReplyCallback;
 import net.dv8tion.jda.api.interactions.components.ComponentInteraction;
+import org.jetbrains.annotations.NotNull;
+import org.jetbrains.annotations.Nullable;
 import org.jetbrains.annotations.Unmodifiable;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
@@ -32,6 +40,7 @@
 import org.togetherjava.tjbot.features.UserContextCommand;
 import org.togetherjava.tjbot.features.UserInteractionType;
 import org.togetherjava.tjbot.features.UserInteractor;
+import org.togetherjava.tjbot.features.VoiceReceiver;
 import org.togetherjava.tjbot.features.componentids.ComponentId;
 import org.togetherjava.tjbot.features.componentids.ComponentIdParser;
 import org.togetherjava.tjbot.features.componentids.ComponentIdStore;
@@ -75,6 +84,7 @@ public final class BotCore extends ListenerAdapter implements CommandProvider {
     private final ComponentIdParser componentIdParser;
     private final ComponentIdStore componentIdStore;
     private final Map<Pattern, MessageReceiver> channelNameToMessageReceiver = new HashMap<>();
+    private final Map<Pattern, VoiceReceiver> channelNameToVoiceReceiver = new HashMap<>();
 
     /**
      * Creates a new command system which uses the given database to allow commands to persist data.
@@ -96,6 +106,13 @@ public BotCore(JDA jda, Database database, Config config) {
             .forEach(messageReceiver -> channelNameToMessageReceiver
                 .put(messageReceiver.getChannelNamePattern(), messageReceiver));
 
+        // Voice receivers
+        features.stream()
+            .filter(VoiceReceiver.class::isInstance)
+            .map(VoiceReceiver.class::cast)
+            .forEach(voiceReceiver -> channelNameToVoiceReceiver
+                .put(voiceReceiver.getChannelNamePattern(), voiceReceiver));
+
         // Event receivers
         features.stream()
             .filter(EventReceiver.class::isInstance)
@@ -238,6 +255,76 @@ public void onMessageDelete(final MessageDeleteEvent event) {
         }
     }
 
+    /**
+     * @param joinChannel the join channel
+     * @param leftChannel the leave channel
+     * @return the join channel if not null, otherwise the leave channel, otherwise an empty
+     *         optional
+     */
+    private Optional<Channel> calculateSubscribeTarget(@Nullable AudioChannelUnion joinChannel,
+            @Nullable AudioChannelUnion leftChannel) {
+        if (joinChannel != null) {
+            return Optional.of(joinChannel);
+        }
+
+        return Optional.ofNullable(leftChannel);
+    }
+
+    @Override
+    public void onGuildVoiceUpdate(@NotNull GuildVoiceUpdateEvent event) {
+        calculateSubscribeTarget(event.getChannelJoined(), event.getChannelLeft())
+            .ifPresent(channel -> getVoiceReceiversSubscribedTo(channel)
+                .forEach(voiceReceiver -> voiceReceiver.onVoiceUpdate(event)));
+    }
+
+    @Override
+    public void onGuildVoiceVideo(@NotNull GuildVoiceVideoEvent event) {
+        AudioChannelUnion channel = event.getVoiceState().getChannel();
+
+        if (channel == null) {
+            return;
+        }
+
+        getVoiceReceiversSubscribedTo(channel)
+            .forEach(voiceReceiver -> voiceReceiver.onVideoToggle(event));
+    }
+
+    @Override
+    public void onGuildVoiceStream(@NotNull GuildVoiceStreamEvent event) {
+        AudioChannelUnion channel = event.getVoiceState().getChannel();
+
+        if (channel == null) {
+            return;
+        }
+
+        getVoiceReceiversSubscribedTo(channel)
+            .forEach(voiceReceiver -> voiceReceiver.onStreamToggle(event));
+    }
+
+    @Override
+    public void onGuildVoiceMute(@NotNull GuildVoiceMuteEvent event) {
+        AudioChannelUnion channel = event.getVoiceState().getChannel();
+
+        if (channel == null) {
+            return;
+        }
+
+        getVoiceReceiversSubscribedTo(channel)
+            .forEach(voiceReceiver -> voiceReceiver.onMuteToggle(event));
+    }
+
+    @Override
+    public void onGuildVoiceDeafen(@NotNull GuildVoiceDeafenEvent event) {
+        AudioChannelUnion channel = event.getVoiceState().getChannel();
+
+        if (channel == null) {
+            return;
+        }
+
+        getVoiceReceiversSubscribedTo(channel)
+            .forEach(voiceReceiver -> voiceReceiver.onDeafenToggle(event));
+    }
+
     private Stream<MessageReceiver> getMessageReceiversSubscribedTo(Channel channel) {
         String channelName = channel.getName();
         return channelNameToMessageReceiver.entrySet()
@@ -248,6 +335,16 @@ private Stream<MessageReceiver> getMessageReceiversSubscribedTo(Channel channel)
             .map(Map.Entry::getValue);
     }
 
+    private Stream<VoiceReceiver> getVoiceReceiversSubscribedTo(Channel channel) {
+        String channelName = channel.getName();
+        return channelNameToVoiceReceiver.entrySet()
+            .stream()
+            .filter(patternAndReceiver -> patternAndReceiver.getKey()
+                .matcher(channelName)
+                .matches())
+            .map(Map.Entry::getValue);
+    }
+
     @Override
     public void onSlashCommandInteraction(SlashCommandInteractionEvent event) {
         String name = event.getName();