Configuration API (#12301)

This implements a solution that preemptively exits the tick loop if we have already marked the connection as disconnecting. This avoids changing the result of Connection#isConnected in order to avoid other possibly unintentional changes. Fundamentally it should be investigated if closing the connection async is really still needed.

This also additionally removes the login disconnecting logic for server stopping, as this was also a possible issue in the config stage but also shouldn't be an issue as connections are closed on server stop very early.

Additionally, do not check for isConnecting() on VERIFYING, as that seemed to be an old diff originally trying to resolve this code, however isConnected is not updated at this point so it pretty much was useless.

Author: Owen1212055

build-data/paper.at

@@ -104,6 +104,9 @@ public net.minecraft.server.level.ServerPlayer wardenSpawnTracker
 public net.minecraft.server.level.ServerPlayer$RespawnPosAngle
 public net.minecraft.server.level.ServerPlayerGameMode level
 public net.minecraft.server.level.TicketType register(Ljava/lang/String;JZLnet/minecraft/server/level/TicketType$TicketUse;)Lnet/minecraft/server/level/TicketType;
+public net.minecraft.server.network.ServerConfigurationPacketListenerImpl clientInformation
+public net.minecraft.server.network.ServerConfigurationPacketListenerImpl currentTask
+public net.minecraft.server.network.ServerConfigurationPacketListenerImpl finishCurrentTask(Lnet/minecraft/server/network/ConfigurationTask$Type;)V
 public net.minecraft.server.network.ServerGamePacketListenerImpl isChatMessageIllegal(Ljava/lang/String;)Z
 public net.minecraft.server.network.ServerLoginPacketListenerImpl authenticatedProfile
 public net.minecraft.server.network.ServerLoginPacketListenerImpl connection

paper-api/src/main/java/io/papermc/paper/connection/PlayerCommonConnection.java

@@ -0,0 +1,45 @@
+package io.papermc.paper.connection;
+
+import java.util.Map;
+
+import com.destroystokyo.paper.ClientOption;
+import org.bukkit.ServerLinks;
+
+/**
+ * Represents a connection that has properties shared between the GAME and CONFIG stage.
+ */
+public interface PlayerCommonConnection extends WritablePlayerCookieConnection, ReadablePlayerCookieConnection {
+
+    /**
+     * Sends data to appear in this connection's report logs.
+     * This is useful for debugging server state that may be causing
+     * player disconnects.
+     * <p>
+     * These are formatted as key - value, where keys are limited to a length of 128 characters,
+     * values are limited to 4096, and 32 maximum entries can be sent.
+     *
+     * @param details report details
+     */
+    void sendReportDetails(Map<String, String> details);
+
+    /**
+     * Sends the given server links to this connection.
+     *
+     * @param links links to send
+     */
+    void sendLinks(ServerLinks links);
+
+    /**
+     * Transfers this connection to another server.
+     *
+     * @param host host
+     * @param port port
+     */
+    void transfer(String host, int port);
+
+    /**
+     * @param type client option
+     * @return the client option value of the player
+     */
+    <T> T getClientOption(ClientOption<T> type);
+}

paper-api/src/main/java/io/papermc/paper/connection/PlayerConfigurationConnection.java

@@ -0,0 +1,37 @@
+package io.papermc.paper.connection;
+
+import com.destroystokyo.paper.ClientOption;
+import com.destroystokyo.paper.profile.PlayerProfile;
+import net.kyori.adventure.audience.Audience;
+
+public interface PlayerConfigurationConnection extends PlayerCommonConnection {
+
+    /**
+     * Returns the audience representing the player in configuration mode.
+     * This can be used to interact with the Adventure API during the configuration stage.
+     * This is guaranteed to be an instance of {@link PlayerConfigurationConnection}
+     *
+     * @return the configuring player audience
+     */
+    Audience getAudience();
+
+    /**
+     * Gets the profile for this connection.
+     *
+     * @return profile
+     */
+    PlayerProfile getProfile();
+
+    /**
+     * Clears the players chat history and their local chat.
+     */
+    void clearChat();
+
+    /**
+     * Completes the configuration for this player, which will cause this player to reenter the game.
+     * <p>
+     * Note, this should be only be called if you are reconfiguring the player.
+     */
+    void completeReconfiguration();
+
+}

paper-api/src/main/java/io/papermc/paper/connection/PlayerConnection.java

@@ -0,0 +1,60 @@
+package io.papermc.paper.connection;
+
+import java.net.InetSocketAddress;
+import java.net.SocketAddress;
+import net.kyori.adventure.text.Component;
+import org.jspecify.annotations.Nullable;
+
+public interface PlayerConnection {
+
+    /**
+     * Disconnects the player connection.
+     * <p>
+     * Note that calling this during connection related events may caused undefined behavior.
+     *
+     * @param component disconnect reason
+     */
+    void disconnect(Component component);
+
+    /**
+     * Gets if this connection originated from a transferred connection.
+     * <p>
+     * Do note that this is sent and stored on the client.
+     *
+     * @return is transferred
+     */
+    boolean isTransferred();
+
+    /**
+     * Gets the raw remote address of the connection. This may be a proxy address
+     * or a Unix domain socket address, depending on how the channel was established.
+     *
+     * @return the remote {@link SocketAddress} of the channel
+     */
+    SocketAddress getAddress();
+
+    /**
+     * Gets the real client address of the player. If the connection is behind a proxy,
+     * this will be the actual player’s IP address extracted from the proxy handshake.
+     *
+     * @return the client {@link InetSocketAddress}
+     */
+    InetSocketAddress getClientAddress();
+
+    /**
+     * Returns the virtual host the client is connected to.
+     *
+     * <p>The virtual host refers to the hostname/port the client used to
+     * connect to the server.</p>
+     *
+     * @return The client's virtual host, or {@code null} if unknown
+     */
+    @Nullable InetSocketAddress getVirtualHost();
+
+    /**
+     * Gets the socket address of this player's proxy
+     *
+     * @return the player's proxy address, null if the server doesn't have Proxy Protocol enabled, or the player didn't connect to an HAProxy instance
+     */
+    @Nullable InetSocketAddress getHAProxyAddress();
+}

paper-api/src/main/java/io/papermc/paper/connection/PlayerGameConnection.java

@@ -0,0 +1,21 @@
+package io.papermc.paper.connection;
+
+import org.bukkit.entity.Player;
+
+public interface PlayerGameConnection extends PlayerCommonConnection {
+
+    /**
+     * Bumps the player to the configuration stage.
+     * <p>
+     * This will, by default, cause the player to stay until their connection is released by
+     * {@link PlayerConfigurationConnection#completeReconfiguration()}
+     */
+    void reenterConfiguration();
+
+    /**
+     * Gets the player that is associated with this game connection.
+     *
+     * @return player
+     */
+    Player getPlayer();
+}

paper-api/src/main/java/io/papermc/paper/connection/PlayerLoginConnection.java

@@ -0,0 +1,23 @@
+package io.papermc.paper.connection;
+
+import com.destroystokyo.paper.profile.PlayerProfile;
+import org.jspecify.annotations.Nullable;
+
+public interface PlayerLoginConnection extends ReadablePlayerCookieConnection {
+
+    /**
+     * Gets the authenticated profile for this connection.
+     * This may return null depending on what stage this connection is at.
+     *
+     * @return authenticated profile, or null if not present
+     */
+    @Nullable PlayerProfile getAuthenticatedProfile();
+
+    /**
+     * Gets the player profile that this connection is requesting to authenticate as.
+     *
+     * @return the unsafe unauthenticated profile, or null if not sent
+     */
+    @Nullable
+    PlayerProfile getUnsafeProfile();
+}

paper-api/src/main/java/io/papermc/paper/connection/ReadablePlayerCookieConnection.java

@@ -0,0 +1,18 @@
+package io.papermc.paper.connection;
+
+import java.util.concurrent.CompletableFuture;
+import org.bukkit.NamespacedKey;
+
+public interface ReadablePlayerCookieConnection extends PlayerConnection {
+
+    /**
+     * Retrieves a cookie from this connection.
+     *
+     * @param key the key identifying the cookie
+     * @return a {@link CompletableFuture} that will be completed when the
+     * Cookie response is received or otherwise available. If the cookie is not
+     * set in the client, the {@link CompletableFuture} will complete with a
+     * null value.
+     */
+    CompletableFuture<byte[]> retrieveCookie(NamespacedKey key);
+}

paper-api/src/main/java/io/papermc/paper/connection/WritablePlayerCookieConnection.java

@@ -0,0 +1,15 @@
+package io.papermc.paper.connection;
+
+import org.bukkit.NamespacedKey;
+
+public interface WritablePlayerCookieConnection extends PlayerConnection {
+
+    /**
+     * Stores a cookie in this player's client.
+     *
+     * @param key the key identifying the cookie
+     * @param value the data to store in the cookie
+     * @throws IllegalStateException if a cookie cannot be stored at this time
+     */
+    void storeCookie(NamespacedKey key, byte[] value);
+}

paper-api/src/main/java/io/papermc/paper/connection/package-info.java

@@ -0,0 +1,9 @@
+/**
+ * This package contains events related to player connections, such as joining and leaving the server.
+ */
+@ApiStatus.Experimental
+@NullMarked
+package io.papermc.paper.connection;
+
+import org.jetbrains.annotations.ApiStatus;
+import org.jspecify.annotations.NullMarked;

paper-api/src/main/java/io/papermc/paper/event/connection/PlayerConnectionValidateLoginEvent.java

@@ -0,0 +1,86 @@
+package io.papermc.paper.event.connection;
+
+import io.papermc.paper.connection.PlayerConnection;
+import net.kyori.adventure.text.Component;
+import org.bukkit.event.Event;
+import org.bukkit.event.HandlerList;
+import org.jetbrains.annotations.ApiStatus;
+import org.jspecify.annotations.Nullable;
+
+/**
+ * Validates whether a player connection is able to log in.
+ * <p>
+ * Called when is attempting to log in for the first time, or is finishing up
+ * being configured.
+ */
+public class PlayerConnectionValidateLoginEvent extends Event {
+
+    private static final HandlerList HANDLER_LIST = new HandlerList();
+
+    private final PlayerConnection connection;
+    private @Nullable Component kickMessage;
+
+    @ApiStatus.Internal
+    public PlayerConnectionValidateLoginEvent(final PlayerConnection connection, final @Nullable Component kickMessage) {
+        super(false);
+        this.connection = connection;
+        this.kickMessage = kickMessage;
+    }
+
+    /**
+     * Gets the connection of the player in this event.
+     * Note, the type of this connection is not guaranteed to be stable across versions.
+     * Additionally, disconnecting the player through this connection / using any methods that may send packets
+     * is not supported.
+     *
+     * @return connection
+     */
+    public PlayerConnection getConnection() {
+        return this.connection;
+    }
+
+    /**
+     * Allows the player to log in.
+     * This skips any login validation checks.
+     */
+    public void allow() {
+        this.kickMessage = null;
+    }
+
+    /**
+     * Disallows the player from logging in, with the given reason
+     *
+     * @param message Kick message to display to the user
+     */
+    public void kickMessage(final Component message) {
+        this.kickMessage = message;
+    }
+
+    /**
+     * Gets the reason for why a player is not allowed to join the server.
+     * This will be null in the case that the player is allowed to log in.
+     *
+     * @return disallow reason
+     */
+    public @Nullable Component getKickMessage() {
+        return this.kickMessage;
+    }
+
+    /**
+     * Gets if the player is allowed to enter the next stage.
+     *
+     * @return if allowed
+     */
+    public boolean isAllowed() {
+        return this.kickMessage == null;
+    }
+
+    @Override
+    public HandlerList getHandlers() {
+        return HANDLER_LIST;
+    }
+
+    public static HandlerList getHandlerList() {
+        return HANDLER_LIST;
+    }
+}