Implement ProtocolState API (#1224)

* Implement ProtocolState API

* Renamed method to #getProtocolState

* Added sinceMinecraft javadoc tag

* Fixed PreLoginEvent#getUniqueId documentation

api/build.gradle.kts

@@ -73,7 +73,8 @@ tasks {
         o.tags(
             "apiNote:a:API Note:",
             "implSpec:a:Implementation Requirements:",
-            "implNote:a:Implementation Note:"
+            "implNote:a:Implementation Note:",
+            "sinceMinecraft:a:Since Minecraft:"
         )
 
         // Disable the crazy super-strict doclint tool in Java 8

api/src/main/java/com/velocitypowered/api/event/connection/PreLoginEvent.java

@@ -72,9 +72,12 @@ public final class PreLoginEvent implements ResultedEvent<PreLoginEvent.PreLogin
   }
 
   /**
-   * Returns the UUID of the connecting player. This value is {@code null} on 1.19.1 and lower.
+   * Returns the UUID of the connecting player.
+   * <p>This value is {@code null} on 1.19.2 and lower,
+   * up to 1.20.1 it is optional and from 1.20.2 it will always be available.</p>
    *
    * @return the uuid
+   * @sinceMinecraft 1.19.3
    */
   public @Nullable UUID getUniqueId() {
     return uuid;

api/src/main/java/com/velocitypowered/api/network/ProtocolState.java

@@ -0,0 +1,52 @@
+/*
+ * Copyright (C) 2024 Velocity Contributors
+ *
+ * The Velocity API is licensed under the terms of the MIT License. For more details,
+ * reference the LICENSE file in the api top-level directory.
+ */
+
+package com.velocitypowered.api.network;
+
+/**
+ * Representation of the state of the protocol
+ * in which a connection can be present.
+ *
+ * @since 3.3.0
+ */
+public enum ProtocolState {
+  /**
+   * Initial connection State.
+   * <p>This status can be caused by a STATUS, LOGIN or TRANSFER intent.</p>
+   * If the intent is LOGIN or TRANSFER, the next state will be {@link #LOGIN},
+   * otherwise, it will go to the {@link #STATUS} state.
+   */
+  HANDSHAKE,
+  /**
+   * Ping State of a connection.
+   * <p>Connections with the STATUS HandshakeIntent will pass through this state
+   * and be disconnected after it requests the ping from the server
+   * and the server responds with the respective ping.</p>
+   */
+  STATUS,
+  /**
+   * Authentication State of a connection.
+   * <p>At this moment the player is authenticating with the authentication servers.</p>
+   */
+  LOGIN,
+  /**
+   * Configuration State of a connection.
+   * <p>At this point the player allows the server to send information
+   * such as resource packs and plugin messages, at the same time the player
+   * will send his client brand and the respective plugin messages
+   * if it is a modded client.</p>
+   *
+   * @sinceMinecraft 1.20.2
+   */
+  CONFIGURATION,
+  /**
+   * Game State of a connection.
+   * <p>In this state is where the whole game runs, the server is able to change
+   * the player's state to {@link #CONFIGURATION} as needed in versions 1.20.2 and higher.</p>
+   */
+  PLAY
+}

api/src/main/java/com/velocitypowered/api/proxy/InboundConnection.java

@@ -7,6 +7,7 @@
 
 package com.velocitypowered.api.proxy;
 
+import com.velocitypowered.api.network.ProtocolState;
 import com.velocitypowered.api.network.ProtocolVersion;
 import java.net.InetSocketAddress;
 import java.util.Optional;
@@ -43,4 +44,11 @@ public interface InboundConnection {
    * @return the protocol version the connection uses
    */
   ProtocolVersion getProtocolVersion();
+
+  /**
+   * Returns the current protocol state of this connection.
+   *
+   * @return the protocol state of the connection
+   */
+  ProtocolState getProtocolState();
 }

api/src/main/java/com/velocitypowered/api/proxy/Player.java

@@ -190,7 +190,7 @@ public interface Player extends
    *
    * @param reason component with the reason
    */
-  void disconnect(net.kyori.adventure.text.Component reason);
+  void disconnect(Component reason);
 
   /**
    * Sends chat input onto the players current server as if they typed it into the client chat box.

api/src/main/java/com/velocitypowered/api/proxy/player/PlayerSettings.java

@@ -64,6 +64,7 @@ public interface PlayerSettings {
    * This feature was introduced in 1.18.
    *
    * @return whether or not the client explicitly allows listing. Always false on older clients.
+   * @sinceMinecraft 1.18
    */
   boolean isClientListingAllowed();
 

proxy/src/main/java/com/velocitypowered/proxy/connection/client/ConnectedPlayer.java

@@ -33,6 +33,7 @@ import com.velocitypowered.api.event.player.KickedFromServerEvent.ServerKickResu
 import com.velocitypowered.api.event.player.PlayerModInfoEvent;
 import com.velocitypowered.api.event.player.PlayerSettingsChangedEvent;
 import com.velocitypowered.api.event.player.ServerPreConnectEvent;
+import com.velocitypowered.api.network.ProtocolState;
 import com.velocitypowered.api.network.ProtocolVersion;
 import com.velocitypowered.api.permission.PermissionFunction;
 import com.velocitypowered.api.permission.PermissionProvider;
@@ -1170,6 +1171,11 @@ public class ConnectedPlayer implements MinecraftConnectionAssociation, Player,
     }
   }
 
+  @Override
+  public ProtocolState getProtocolState() {
+    return connection.getState().toProtocolState();
+  }
+
   private final class ConnectionRequestBuilderImpl implements ConnectionRequestBuilder {
 
     private final RegisteredServer toConnect;

proxy/src/main/java/com/velocitypowered/proxy/connection/client/HandshakeSessionHandler.java

@@ -20,6 +20,7 @@ package com.velocitypowered.proxy.connection.client;
 import com.google.common.annotations.VisibleForTesting;
 import com.google.common.base.Preconditions;
 import com.velocitypowered.api.event.connection.ConnectionHandshakeEvent;
+import com.velocitypowered.api.network.ProtocolState;
 import com.velocitypowered.api.network.ProtocolVersion;
 import com.velocitypowered.proxy.VelocityServer;
 import com.velocitypowered.proxy.config.PlayerInfoForwarding;
@@ -247,9 +248,9 @@ public class HandshakeSessionHandler implements MinecraftSessionHandler {
 
     @Override
     public String toString() {
-      boolean isPlayerAddressLoggingEnabled = connection.server.getConfiguration()
+      final boolean isPlayerAddressLoggingEnabled = connection.server.getConfiguration()
           .isPlayerAddressLoggingEnabled();
-      String playerIp =
+      final String playerIp =
           isPlayerAddressLoggingEnabled
               ? this.getRemoteAddress().toString() : "<ip address withheld>";
       return "[legacy connection] " + playerIp;
@@ -259,5 +260,10 @@ public class HandshakeSessionHandler implements MinecraftSessionHandler {
     public MinecraftConnection getConnection() {
       return connection;
     }
+
+    @Override
+    public ProtocolState getProtocolState() {
+      return connection.getState().toProtocolState();
+    }
   }
 }

proxy/src/main/java/com/velocitypowered/proxy/connection/client/InitialInboundConnection.java

@@ -17,6 +17,7 @@
 
 package com.velocitypowered.proxy.connection.client;
 
+import com.velocitypowered.api.network.ProtocolState;
 import com.velocitypowered.api.network.ProtocolVersion;
 import com.velocitypowered.api.proxy.InboundConnection;
 import com.velocitypowered.proxy.connection.MinecraftConnection;
@@ -87,6 +88,11 @@ public final class InitialInboundConnection implements VelocityInboundConnection
     return connection;
   }
 
+  @Override
+  public ProtocolState getProtocolState() {
+    return connection.getState().toProtocolState();
+  }
+
   /**
    * Disconnects the connection from the server.
    *

proxy/src/main/java/com/velocitypowered/proxy/connection/client/LoginInboundConnection.java

@@ -17,6 +17,7 @@
 
 package com.velocitypowered.proxy.connection.client;
 
+import com.velocitypowered.api.network.ProtocolState;
 import com.velocitypowered.api.network.ProtocolVersion;
 import com.velocitypowered.api.proxy.LoginPhaseConnection;
 import com.velocitypowered.api.proxy.crypto.IdentifiedKey;
@@ -166,4 +167,9 @@ public class LoginInboundConnection implements LoginPhaseConnection, KeyIdentifi
   public IdentifiedKey getIdentifiedKey() {
     return playerKey;
   }
+
+  @Override
+  public ProtocolState getProtocolState() {
+    return delegate.getProtocolState();
+  }
 }

proxy/src/main/java/com/velocitypowered/proxy/protocol/StateRegistry.java

@@ -45,6 +45,7 @@ import static com.velocitypowered.proxy.protocol.ProtocolUtils.Direction;
 import static com.velocitypowered.proxy.protocol.ProtocolUtils.Direction.CLIENTBOUND;
 import static com.velocitypowered.proxy.protocol.ProtocolUtils.Direction.SERVERBOUND;
 
+import com.velocitypowered.api.network.ProtocolState;
 import com.velocitypowered.api.network.ProtocolVersion;
 import com.velocitypowered.proxy.protocol.packet.AvailableCommandsPacket;
 import com.velocitypowered.proxy.protocol.packet.BossBarPacket;
@@ -623,6 +624,21 @@ public enum StateRegistry {
     return (direction == SERVERBOUND ? serverbound : clientbound).getProtocolRegistry(version);
   }
 
+  /**
+   * Gets the API representation of the StateRegistry.
+   *
+   * @return the API representation
+   */
+  public ProtocolState toProtocolState() {
+    return switch (this) {
+      case HANDSHAKE -> ProtocolState.HANDSHAKE;
+      case STATUS -> ProtocolState.STATUS;
+      case LOGIN -> ProtocolState.LOGIN;
+      case CONFIG -> ProtocolState.CONFIGURATION;
+      case PLAY -> ProtocolState.PLAY;
+    };
+  }
+
   /**
    * Packet registry.
    */