001package andesite.handler;
002
003import andesite.util.metadata.MetadataEntry;
004import andesite.util.metadata.NamePartJoiner;
005import io.vertx.core.json.JsonObject;
006
007import javax.annotation.CheckReturnValue;
008import javax.annotation.Nonnull;
009import javax.annotation.Nullable;
010import java.util.Map;
011import java.util.concurrent.CompletionStage;
012import java.util.function.Consumer;
013
014public interface AndesiteRequestHandler {
015    /**
016     * Returns a map of the metadata fields to their values. The keys
017     * will be formatted based on the provided {@link NamePartJoiner}.
018     *
019     * @param joiner Formatter for the map keys.
020     *
021     * @return The metadata map.
022     */
023    @Nonnull
024    @CheckReturnValue
025    Map<String, MetadataEntry> metadataFields(@Nonnull NamePartJoiner joiner);
026    
027    /**
028     * Provides a voice server update. The provided json object must be a valid
029     * voice update payload.
030     *
031     * @param userId User id for the payload.
032     * @param json   Voice update payload.
033     */
034    void provideVoiceServerUpdate(@Nonnull String userId, @Nonnull JsonObject json);
035    
036    /**
037     * Returns the encoded player, if it exists.
038     *
039     * @param userId  User id of the player.
040     * @param guildId Guild id of the player.
041     *
042     * @return The encoded player, or null if it doesn't exist.
043     */
044    @Nullable
045    JsonObject player(@Nonnull String userId, @Nonnull String guildId);
046    
047    /**
048     * Subscribes a provided sink to receive events for the player.
049     * The sink should forward the events to clients.
050     *
051     * @param userId    User id of the player.
052     * @param guildId   Guild id of the player.
053     * @param key       Unique key identifying this consumer. Anything works, as long as it's unique.
054     * @param eventSink Sink for events.
055     */
056    void subscribe(@Nonnull String userId, @Nonnull String guildId,
057                   @Nonnull Object key, @Nonnull Consumer<JsonObject> eventSink);
058    
059    /**
060     * Handles a play payload. Returns the player state.
061     *
062     * @param userId  User id of the player.
063     * @param guildId Guild id of the player.
064     * @param payload Payload to handle.
065     *
066     * @return The player state.
067     */
068    @Nonnull
069    JsonObject play(@Nonnull String userId, @Nonnull String guildId, @Nonnull JsonObject payload);
070    
071    /**
072     * Handles a mixer payload. Returns the player state.
073     *
074     * @param userId  User id of the player.
075     * @param guildId Guild id of the player.
076     * @param payload Payload to handle.
077     *
078     * @return The player state.
079     */
080    @Nonnull
081    JsonObject mixer(@Nonnull String userId, @Nonnull String guildId, @Nonnull JsonObject payload);
082    
083    /**
084     * Handles a stop request. Returns the player state.
085     *
086     * @param userId  User id of the player.
087     * @param guildId Guild id of the player.
088     *
089     * @return The player state.
090     */
091    @Nonnull
092    JsonObject stop(@Nonnull String userId, @Nonnull String guildId);
093    
094    /**
095     * Handles a pause payload. Returns the player state.
096     *
097     * @param userId  User id of the player.
098     * @param guildId Guild id of the player.
099     * @param payload Payload to handle.
100     *
101     * @return The player state.
102     */
103    @Nonnull
104    JsonObject pause(@Nonnull String userId, @Nonnull String guildId, @Nonnull JsonObject payload);
105    
106    /**
107     * Handles a seek payload. Returns the player state.
108     *
109     * @param userId  User id of the player.
110     * @param guildId Guild id of the player.
111     * @param payload Payload to handle.
112     *
113     * @return The player state.
114     */
115    @Nonnull
116    JsonObject seek(@Nonnull String userId, @Nonnull String guildId, @Nonnull JsonObject payload);
117    
118    /**
119     * Handles a volume payload. Returns the player state.
120     *
121     * @param userId  User id of the player.
122     * @param guildId Guild id of the player.
123     * @param payload Payload to handle.
124     *
125     * @return The player state.
126     */
127    @Nonnull
128    JsonObject volume(@Nonnull String userId, @Nonnull String guildId, @Nonnull JsonObject payload);
129    
130    /**
131     * Handles a filters payload. Returns the player state.
132     *
133     * @param userId  User id of the player.
134     * @param guildId Guild id of the player.
135     * @param payload Payload to handle.
136     *
137     * @return The player state.
138     */
139    @Nonnull
140    JsonObject filters(@Nonnull String userId, @Nonnull String guildId, @Nonnull JsonObject payload);
141    
142    /**
143     * Handles an update payload. Returns the player state.
144     *
145     * @param userId  User id of the player.
146     * @param guildId Guild id of the player.
147     * @param payload Payload to handle.
148     *
149     * @return The player state.
150     */
151    @Nonnull
152    JsonObject update(@Nonnull String userId, @Nonnull String guildId, @Nonnull JsonObject payload);
153    
154    /**
155     * Handles a destroy request. Returns the player state.
156     *
157     * @param userId  User id of the player.
158     * @param guildId Guild id of the player.
159     * @param cleanup Whether or not this player is being destroyed by an automatic cleanup.
160     *
161     * @return The player state, or null if it doesn't exist.
162     */
163    @Nullable
164    JsonObject destroy(@Nonnull String userId, @Nonnull String guildId, boolean cleanup);
165    
166    /**
167     * Resolves tracks with the provided identifier.
168     *
169     * <br>If the identifier is a string, starts with {@code ytsearch:} or {@code scsearch:}, it's
170     * used as-is for loading.
171     * <br>If it starts with {@code raw:}, the first 4 characters (raw:) are removed and the rest
172     * is used for loading.
173     * <br>Otherwise, the identifier is prepended with {@code ytsearch:} and used for loading.
174     *
175     * @param identifier Identifier to load.
176     *
177     * @return The result of the track lookup.
178     */
179    @Nonnull
180    @CheckReturnValue
181    CompletionStage<JsonObject> resolveTracks(@Nonnull String identifier);
182    
183    /**
184     * Returns the stats of the node.
185     *
186     * @return The stats of the node.
187     */
188    @Nonnull
189    @CheckReturnValue
190    JsonObject nodeStats();
191    
192    /**
193     * Returns lavalink compatible stats of the node.
194     *
195     * @return Lavalink compatible stats of the node.
196     */
197    @Nonnull
198    @CheckReturnValue
199    JsonObject nodeStatsForLavalink();
200}