From afb6e69388a3805a4fd8aa1f97ef60758535bcac Mon Sep 17 00:00:00 2001
From: Andrew Steinborn <git@steinborn.me>
Date: Fri, 24 Aug 2018 21:09:56 -0400
Subject: [PATCH] Improve Javadoc and the GameProfileRequestEvent.

---
 .../api/command/CommandManager.java           | 15 ++++++++++
 .../api/event/connection/PreLoginEvent.java   | 23 +++++++++++----
 .../gameprofile/GameProfileRequestEvent.java  | 28 +++++++++++++++----
 .../client/LoginSessionHandler.java           |  3 +-
 4 files changed, 57 insertions(+), 12 deletions(-)

diff --git a/api/src/main/java/com/velocitypowered/api/command/CommandManager.java b/api/src/main/java/com/velocitypowered/api/command/CommandManager.java
index 38f031716..040c3d295 100644
--- a/api/src/main/java/com/velocitypowered/api/command/CommandManager.java
+++ b/api/src/main/java/com/velocitypowered/api/command/CommandManager.java
@@ -6,9 +6,24 @@ import org.checkerframework.checker.nullness.qual.NonNull;
  * Represents an interface to register a command executor with the proxy.
  */
 public interface CommandManager {
+    /**
+     * Registers the specified command with the manager with the specified aliases.
+     * @param command the command to register
+     * @param aliases the alias to use
+     */
     void register(@NonNull Command command, String... aliases);
 
+    /**
+     * Unregisters a command.
+     * @param alias the command alias to unregister
+     */
     void unregister(@NonNull String alias);
 
+    /**
+     * Attempts to execute a command from the specified {@code cmdLine}.
+     * @param source the command's source
+     * @param cmdLine the command to run
+     * @return true if the command was found and executed, false if it was not
+     */
     boolean execute(@NonNull CommandSource source, @NonNull String cmdLine);
 }
diff --git a/api/src/main/java/com/velocitypowered/api/event/connection/PreLoginEvent.java b/api/src/main/java/com/velocitypowered/api/event/connection/PreLoginEvent.java
index 9c052df96..169427850 100644
--- a/api/src/main/java/com/velocitypowered/api/event/connection/PreLoginEvent.java
+++ b/api/src/main/java/com/velocitypowered/api/event/connection/PreLoginEvent.java
@@ -2,7 +2,6 @@ package com.velocitypowered.api.event.connection;
 
 import com.google.common.base.Preconditions;
 import com.velocitypowered.api.event.ResultedEvent;
-import com.velocitypowered.api.event.ResultedEvent.ComponentResult;
 import com.velocitypowered.api.proxy.InboundConnection;
 
 import net.kyori.text.Component;
@@ -57,15 +56,14 @@ public class PreLoginEvent implements ResultedEvent<PreLoginEvent.PreLoginCompon
      * Represents an "allowed/allowed with online mode/denied" result with a reason allowed for denial.
      */
     public static class PreLoginComponentResult extends ComponentResult {
-
         private static final PreLoginComponentResult ALLOWED = new PreLoginComponentResult((Component) null);
         private static final PreLoginComponentResult FORCE_ONLINEMODE = new PreLoginComponentResult(true);
 
         private final boolean onlineMode;
+
         /**
-         * Allows to enable a online mode for the player connection, when Velocity running in offline mode
-         * Does not have any sense if velocity running in onlineMode;
-         * @param allowedOnlineMode if true, offline uuid will be used for player connection if Velocity run in offlineMode
+         * Allows online mode to be enabled for the player connection, if Velocity is running in offline mode.
+         * @param allowedOnlineMode if true, online mode will be used for the connection
          */
         private PreLoginComponentResult(boolean allowedOnlineMode) {
             super(true, null);
@@ -91,14 +89,29 @@ public class PreLoginEvent implements ResultedEvent<PreLoginEvent.PreLoginCompon
             return super.toString();
         }
 
+        /**
+         * Returns a result indicating the connection will be allowed through the proxy.
+         * @return the allowed result
+         */
         public static PreLoginComponentResult allowed() {
             return ALLOWED;
         }
 
+        /**
+         * Returns a result indicating the connection will be allowed through the proxy, but the connection will be
+         * forced to use online mode provided that the proxy is in offline mode. This acts similarly to {@link #allowed()}
+         * on an online-mode proxy.
+         * @return the result
+         */
         public static PreLoginComponentResult forceOnlineMode() {
             return FORCE_ONLINEMODE;
         }
 
+        /**
+         * Denies the login with the specified reason.
+         * @param reason the reason for disallowing the connection
+         * @return a new result
+         */
         public static PreLoginComponentResult denied(@NonNull Component reason) {
             Preconditions.checkNotNull(reason, "reason");
             return new PreLoginComponentResult(reason);
diff --git a/api/src/main/java/com/velocitypowered/api/event/player/gameprofile/GameProfileRequestEvent.java b/api/src/main/java/com/velocitypowered/api/event/player/gameprofile/GameProfileRequestEvent.java
index 4ec4fa6d8..2630ac5a0 100644
--- a/api/src/main/java/com/velocitypowered/api/event/player/gameprofile/GameProfileRequestEvent.java
+++ b/api/src/main/java/com/velocitypowered/api/event/player/gameprofile/GameProfileRequestEvent.java
@@ -1,23 +1,33 @@
 package com.velocitypowered.api.event.player.gameprofile;
 
+import com.velocitypowered.api.proxy.InboundConnection;
 import org.checkerframework.checker.nullness.qual.Nullable;
 
 import com.google.common.base.Preconditions;
 import com.velocitypowered.api.util.GameProfile;
 
-
+/**
+ * This event is fired after the {@link com.velocitypowered.api.event.connection.PreLoginEvent} in order to set up the
+ * game profile for the user. This can be used to configure a custom profile for a user, i.e. skin replacement.
+ */
 public class GameProfileRequestEvent {
     private final String username;
+    private final InboundConnection connection;
     private final GameProfile originalProfile;
     private final boolean onlineMode;
     private GameProfile gameProfile;
 
-    public GameProfileRequestEvent(GameProfile originalProfile, boolean onlinemode) {
+    public GameProfileRequestEvent(InboundConnection connection, GameProfile originalProfile, boolean onlinemode) {
+        this.connection = connection;
         this.originalProfile = Preconditions.checkNotNull(originalProfile, "profile");
         this.username = originalProfile.getName();
         this.onlineMode = onlinemode;
     }
 
+    public InboundConnection getConnection() {
+        return connection;
+    }
+
     public String getUsername() {
         return username;
     }
@@ -29,15 +39,23 @@ public class GameProfileRequestEvent {
     public boolean isOnlineMode() {
         return onlineMode;
     }
+
     /**
-     * 
-     * @return a GameProfile, can be null
+     * Returns the game profile that will be used to initialize the connection with. Should no profile be currently
+     * specified, the one generated by the proxy (for offline mode) or retrieved from the Mojang session servers (for
+     * online mode).
+     * @return the user's {@link GameProfile}
      */
     public GameProfile getGameProfile() {
-        return gameProfile;
+        return gameProfile == null ? originalProfile : gameProfile;
     }
 
+    /**
+     * Sets the game profile to use for this connection. Using this method on an online-mode connection is invalid.
+     * @param gameProfile the profile to use for the connection, {@code null} uses the original profile
+     */
     public void setGameProfile(@Nullable GameProfile gameProfile) {
+        Preconditions.checkState(!onlineMode, "Connection is in online mode, profiles can not be faked");
         this.gameProfile = gameProfile;
     }
 
diff --git a/proxy/src/main/java/com/velocitypowered/proxy/connection/client/LoginSessionHandler.java b/proxy/src/main/java/com/velocitypowered/proxy/connection/client/LoginSessionHandler.java
index 0765bcdcd..754864b7b 100644
--- a/proxy/src/main/java/com/velocitypowered/proxy/connection/client/LoginSessionHandler.java
+++ b/proxy/src/main/java/com/velocitypowered/proxy/connection/client/LoginSessionHandler.java
@@ -160,8 +160,7 @@ public class LoginSessionHandler implements MinecraftSessionHandler {
     }
 
     private void initializePlayer(GameProfile profile, boolean onlineMode) {
-
-        GameProfileRequestEvent profileRequestEvent = new GameProfileRequestEvent(profile, onlineMode);
+        GameProfileRequestEvent profileRequestEvent = new GameProfileRequestEvent(apiInbound, profile, onlineMode);
 
         VelocityServer.getServer().getEventManager().fire(profileRequestEvent).thenCompose(profileEvent -> {
             // Initiate a regular connection and move over to it.