WIP Configuration API

Author: Owen1212055

notes.md

@@ -0,0 +1,15 @@
+- Cookie handling is now async on login + works better, able to be requested at any stage.
+
+Previously, the cookie handling for login occurred after the PlayerLoginEvent only. This meant that cookies could not be sent before the player was created.
+New Use Cases:
+- Instantly terminate the connection if a cookie is not present.
+
+Behavior changes:
+- PlayerLoginEvent no longer blocks cookies
+- PlayerLoginEvent now triggers twice due to reasons 
+- Disconnecting a duplicate player no longer causes a forced save. Check to make sure that still occurs
+
+TODO:
+- PlayerLinksSendEvent
+- Figure out connection hierarchy 
+- Figure out naming

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

@@ -0,0 +1,29 @@
+package io.papermc.paper.connection;
+
+import org.bukkit.NamespacedKey;
+import org.jspecify.annotations.NullMarked;
+import java.util.concurrent.CompletableFuture;
+
+@NullMarked
+public interface CookieConnection 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);
+
+    /**
+     * 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/PlayerConfigurationConnection.java

@@ -0,0 +1,58 @@
+package io.papermc.paper.connection;
+
+import com.destroystokyo.paper.profile.PlayerProfile;
+import org.checkerframework.checker.nullness.qual.Nullable;
+import org.jetbrains.annotations.NotNull;
+import org.jspecify.annotations.NullMarked;
+import java.net.InetAddress;
+import java.net.InetSocketAddress;
+
+@NullMarked
+public interface PlayerConfigurationConnection extends CookieConnection {
+
+    /**
+     * Gets the profile for this connection.
+     * @return profile
+     */
+    PlayerProfile getProfile();
+
+    /**
+     * Gets the player IP address.
+     *
+     * @return The IP address
+     */
+    @NotNull
+    InetAddress getAddress();
+    /**
+     * Gets the raw address of the player logging in
+     * @return The address
+     */
+    @NotNull
+    InetAddress getRawAddress();
+
+    /**
+     * Gets the hostname that the player used to connect to the server, or
+     * blank if unknown
+     *
+     * @return The hostname
+     */
+    @NotNull
+    String getHostname();
+
+    boolean isTransferred();
+
+    /**
+     * Clears the players chat history and their local chat.
+     */
+    void clearChat();
+
+    /**
+     * Note, this should be only be called if you are reconfiguring the player.
+     * Calling this on initial configuration will caused undefined behavior.
+     */
+    void completeConfiguration();
+
+    <T> T getClientOption(com.destroystokyo.paper.ClientOption<T> type);
+
+    void transfer(String host, int port);
+}

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

@@ -0,0 +1,10 @@
+package io.papermc.paper.connection;
+
+import net.kyori.adventure.text.Component;
+import org.bukkit.entity.Player;
+
+public interface PlayerConnection {
+
+    void disconnect(Component component);
+
+}

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

@@ -0,0 +1,17 @@
+package io.papermc.paper.connection;
+
+import org.bukkit.entity.Player;
+
+public interface PlayerGameConnection extends CookieConnection {
+
+
+    /**
+     * 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#completeConfiguration()}
+     */
+    void configurate();
+
+    Player getPlayer();
+}

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

@@ -0,0 +1,52 @@
+package io.papermc.paper.connection;
+
+import com.destroystokyo.paper.profile.PlayerProfile;
+import org.bukkit.NamespacedKey;
+import org.checkerframework.checker.nullness.qual.Nullable;
+import org.jetbrains.annotations.NotNull;
+import org.jspecify.annotations.NullMarked;
+import java.io.IOException;
+import java.net.InetAddress;
+import java.net.InetSocketAddress;
+
+@NullMarked
+public interface PlayerLoginConnection extends CookieConnection  {
+
+    /**
+     * 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 currently present
+     */
+    @Nullable
+    PlayerProfile getAuthenticatedProfile();
+
+    /**
+     * Gets the player IP address.
+     *
+     * @return The IP address
+     */
+    @NotNull
+    InetAddress getAddress();
+    /**
+     * Gets the raw address of the player logging in
+     * @return The address
+     */
+    @NotNull
+    InetAddress getRawAddress();
+
+    /**
+     * Gets the hostname that the player used to connect to the server, or
+     * blank if unknown
+     *
+     * @return The hostname
+     */
+    @NotNull
+    String getHostname();
+
+    boolean isTransferred();
+
+    // TODO: Should we have a read-only interface?
+    @Deprecated
+    @Override
+    void storeCookie(NamespacedKey key, byte[] value) throws UnsupportedOperationException;
+}

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

@@ -0,0 +1,101 @@
+package io.papermc.paper.event.connection.common;
+
+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.jetbrains.annotations.NotNull;
+
+/**
+ * Validates whether a player connection would be able to login at this event.
+ * <p>
+ * Currently, this occurs when the player connection is attempting to log in for the first time, or is finishing up
+ * being configured.
+ */
+// TODO: I am not sure about this event however. I have seen the most common reasons for needing a LoginEvent is to prevent the fullness check. Should we add a separate event for each case? Like WhitelistVerifyEvent?
+public class PlayerConnectionValidateLoginEvent extends Event {
+    private static final HandlerList handlers = new HandlerList();
+
+    private final PlayerConnection connection;
+    private Result result;
+    private Component message;
+
+    @ApiStatus.Internal
+    public PlayerConnectionValidateLoginEvent(PlayerConnection connection, final Result result, final Component message) {
+        super(false);
+        this.connection = connection;
+        this.result = result;
+        this.message = message;
+    }
+
+    public PlayerConnection getConnection() {
+        return connection;
+    }
+
+    public Component getMessage() {
+        return message;
+    }
+
+    public Result getResult() {
+        return result;
+    }
+
+    /**
+     * Allows the player to log in
+     */
+    public void allow() {
+        result = Result.ALLOWED;
+        message = net.kyori.adventure.text.Component.empty();
+    }
+
+    /**
+     * Disallows the player from logging in, with the given reason
+     *
+     * @param result New result for disallowing the player
+     * @param message Kick message to display to the user
+     */
+    public void disallow(@NotNull final Result result, @NotNull final net.kyori.adventure.text.Component message) {
+        this.result = result;
+        this.message = message;
+    }
+
+    /**
+     * Basic kick reasons for communicating to plugins
+     */
+    public enum Result {
+
+        /**
+         * The player is allowed to log in
+         */
+        ALLOWED,
+        /**
+         * The player is not allowed to log in, due to the server being full
+         */
+        KICK_FULL,
+        /**
+         * The player is not allowed to log in, due to them being banned
+         */
+        KICK_BANNED,
+        /**
+         * The player is not allowed to log in, due to them not being on the
+         * white list
+         */
+        KICK_WHITELIST,
+        /**
+         * The player is not allowed to log in, for reasons undefined
+         */
+        KICK_OTHER
+    }
+
+    @NotNull
+    @Override
+    public HandlerList getHandlers() {
+        return handlers;
+    }
+
+    @NotNull
+    public static HandlerList getHandlerList() {
+        return handlers;
+    }
+}

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

@@ -0,0 +1,33 @@
+package io.papermc.paper.event.connection.configuration;
+
+import io.papermc.paper.connection.PlayerConfigurationConnection;
+import org.bukkit.event.HandlerList;
+import org.jetbrains.annotations.ApiStatus;
+import org.jetbrains.annotations.NotNull;
+
+/**
+ * A task that allows you to configurate the player.
+ * This is async and allows you to run configuration code on the player.
+ * Once this event has finished execution, the player connection will continue.
+ * <p>
+ * This occurs after configuration, but before the player has entered the world.
+ */
+public class AsyncPlayerConnectionConfigurateEvent extends PlayerConfigurationConnectionEvent {
+    private static final HandlerList handlers = new HandlerList();
+
+    @ApiStatus.Internal
+    public AsyncPlayerConnectionConfigurateEvent(PlayerConfigurationConnection connection) {
+        super(true, connection);
+    }
+
+    @NotNull
+    @Override
+    public HandlerList getHandlers() {
+        return handlers;
+    }
+
+    @NotNull
+    public static HandlerList getHandlerList() {
+        return handlers;
+    }
+}

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

@@ -0,0 +1,22 @@
+package io.papermc.paper.event.connection.configuration;
+
+import io.papermc.paper.connection.PlayerConfigurationConnection;
+import io.papermc.paper.connection.PlayerLoginConnection;
+import org.bukkit.event.Event;
+
+abstract class PlayerConfigurationConnectionEvent extends Event {
+    private final PlayerConfigurationConnection loginConnection;
+
+    protected PlayerConfigurationConnectionEvent(final PlayerConfigurationConnection loginConnection) {
+        this.loginConnection = loginConnection;
+    }
+
+    protected PlayerConfigurationConnectionEvent(final boolean async, final PlayerConfigurationConnection loginConnection) {
+        super(async);
+        this.loginConnection = loginConnection;
+    }
+
+    public PlayerConfigurationConnection getConfigurationConnection() {
+        return this.loginConnection;
+    }
+}

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

@@ -0,0 +1,27 @@
+package io.papermc.paper.event.connection.configuration;
+
+import io.papermc.paper.connection.PlayerConfigurationConnection;
+import org.bukkit.Bukkit;
+import org.bukkit.event.HandlerList;
+import org.jetbrains.annotations.ApiStatus;
+import org.jetbrains.annotations.NotNull;
+
+public class PlayerConnectionInitialConfigurateEvent extends PlayerConfigurationConnectionEvent {
+    private static final HandlerList handlers = new HandlerList();
+
+    @ApiStatus.Internal
+    public PlayerConnectionInitialConfigurateEvent(PlayerConfigurationConnection connection) {
+        super(!Bukkit.isPrimaryThread(), connection);
+    }
+
+    @NotNull
+    @Override
+    public HandlerList getHandlers() {
+        return handlers;
+    }
+
+    @NotNull
+    public static HandlerList getHandlerList() {
+        return handlers;
+    }
+}