feat(api): add basic packet processing interfaces

src/main/java/dev/protocollib/api/BinaryPacket.java

@@ -1,8 +1,22 @@
 package dev.protocollib.api;
 
+/**
+ * Representing a raw binary packet with a packet id and payload.
+ */
 public interface BinaryPacket {
 
+    /**
+     * Retrieves the packet id.
+     *
+     * @return the packet ID
+     */
     int id();
 
+    /**
+     * Retrieves the payload (data) of the packet.
+     *
+     * @return the packet payload as a byte array
+     */
     byte[] payload();
 }
+

src/main/java/dev/protocollib/api/Connection.java

@@ -1,30 +1,95 @@
 package dev.protocollib.api;
 
 import java.net.InetSocketAddress;
-
-import javax.annotation.Nullable;
+import java.util.Optional;
 
 import org.bukkit.entity.Player;
 
+import dev.protocollib.api.listener.PacketSentListener;
+
+/**
+ * Representing a connection of a player.
+ */
 public interface Connection {
 
-    @Nullable
-    Player player();
+    /**
+     * Retrieves the player associated with the connection, if available.
+     *
+     * @return an optional containing the player, or empty if the player is not present
+     */
+    Optional<Player> player();
 
+    /**
+     * Retrieves the address of the connection.
+     *
+     * @return the remote address of the connection
+     */
     InetSocketAddress address();
 
+    /**
+     * Retrieves the protocol version used by the connection.
+     *
+     * @return the protocol version
+     */
     int protocolVersion();
 
-    ProtocolPhase protocolPhase(PacketDirection packetDirection);
+    /**
+     * Retrieves the current protocol phase of the connection for a given direction.
+     *
+     * @param packetDirection the direction of the packet (clientbound or serverbound)
+     * @return the protocol phase of the connection
+     */
+    ProtocolPhase protocolPhase(ProtocolDirection packetDirection);
 
+    /**
+     * Checks if the connection is currently open.
+     *
+     * @return true if the connection is open, false otherwise
+     */
     boolean isConnected();
 
+    /**
+     * Sends a binary packet over the connection.
+     *
+     * @param packet the binary packet to send
+     */
     void sendPacket(BinaryPacket packet);
 
+    /**
+     * Sends a binary packet over the connection and registers a listener for when the packet is sent.
+     *
+     * @param packet   the binary packet to send
+     * @param listener the listener to invoke once the packet is sent
+     */
+    void sendPacket(BinaryPacket packet, PacketSentListener listener);
+
+    /**
+     * Sends a packet container over the connection.
+     *
+     * @param packet the packet container to send
+     */
     void sendPacket(PacketContainer packet);
 
+    /**
+     * Sends a packet container over the connection and registers a listener for when the packet is sent.
+     *
+     * @param packet   the packet container to send
+     * @param listener the listener to invoke once the packet is sent
+     */
+    void sendPacket(PacketContainer packet, PacketSentListener listener);
+
+    /**
+     * Receives a packet container from the connection.
+     *
+     * @param packet the packet container received
+     */
     void receivePacket(PacketContainer packet);
 
+    /**
+     * Disconnects the connection with the specified reason.
+     *
+     * @param reason the reason for disconnecting
+     */
     void disconnect(String reason);
 
 }

src/main/java/dev/protocollib/api/PacketContainer.java

@@ -1,9 +1,22 @@
 package dev.protocollib.api;
 
+/**
+ * Representing a container for a packet.
+ */
 public interface PacketContainer {
 
+    /**
+     * Retrieves the type of the packet.
+     *
+     * @return the packet type
+     */
     PacketType packetType();
 
+    /**
+     * Retrieves the raw packet object.
+     *
+     * @return the packet object
+     */
     Object packet();
 
 }

src/main/java/dev/protocollib/api/PacketType.java

@@ -1,13 +1,40 @@
 package dev.protocollib.api;
 
-public interface PacketType {
+import java.util.Optional;
 
-    PacketDirection packetDirection();
+import net.kyori.adventure.key.Keyed;
 
-    Class<?> packetClass();
+/**
+ * Representing the type of a network packet.
+ * 
+ * <p>A {@code PacketType} identifies a specific type of packet in the protocol,
+ * including information about its direction, associated class (if any), and 
+ * whether the packet is currently supported.</p>
+ */
+public interface PacketType extends Keyed {
 
-    boolean isSupported();
+    /**
+     * Retrieves the direction in which the packet is being sent.
+     *
+     * @return the {@link ProtocolDirection} of the packet, either clientbound or serverbound
+     */
+    ProtocolDirection protocolDirection();
+
+    /**
+     * Retrieves the class associated with the packet type, if available.
+     * 
+     * <p>Not all packet types have an associated class. If there is no class, 
+     * an empty {@link Optional} is returned.</p>
+     *
+     * @return an {@link Optional} containing the class of the packet, or empty if not applicable
+     */
+    Optional<Class<?>> packetClass();
 
-    boolean isDeprecated();
+    /**
+     * Checks whether the packet type is supported by the current protocol version.
+     *
+     * @return {@code true} if the packet type is supported, {@code false} otherwise
+     */
+    boolean isSupported();
 
 }

src/main/java/dev/protocollib/api/ProtocolDirection.java

@@ -0,0 +1,14 @@
+package dev.protocollib.api;
+
+/**
+ * Representing the direction of a packet, either sent to or from the server.
+ */
+public enum ProtocolDirection {
+
+    /** Packet sent from the client to the server. */
+    SERVERBOUND, 
+
+    /** Packet sent from the server to the client. */
+    CLIENTBOUND;
+
+}

src/main/java/dev/protocollib/api/ProtocolLib.java

@@ -3,10 +3,43 @@
 import org.bukkit.entity.Player;
 import org.bukkit.plugin.Plugin;
 
+import dev.protocollib.api.listener.PacketListenerBuilder;
+
+/**
+ * Representing the main entry point for the ProtocolLib API.
+ */
 public interface ProtocolLib {
 
+	/**
+     * Creates a packet listener for the provided plugin.
+     *
+     * @param plugin the plugin registering the packet listener
+     * @return a builder to configure and register the packet listener
+     */
     PacketListenerBuilder createListener(Plugin plugin);
-
+
+    /**
+     * Retrieves the connection associated with a specific player.
+     *
+     * @param player the player whose connection is being retrieved
+     * @return the connection for the specified player
+     */
     Connection connection(Player player);
 
+    /**
+     * Creates a new binary packet with the given type and payload.
+     *
+     * @param packetType the type of the packet to create
+     * @param payload the binary payload to include in the packet
+     * @return a new {@link BinaryPacket} instance
+     */
+    BinaryPacket createBinaryPacket(PacketType packetType, byte[] payload);
+
+    /**
+     * Creates a new packet container for the given packet type.
+     *
+     * @param packetType the type of the packet to create
+     * @return a new {@link PacketContainer} instance
+     */
+    PacketContainer createPacket(PacketType packetType);
 }

src/main/java/dev/protocollib/api/ProtocolPhase.java

@@ -1,5 +1,8 @@
 package dev.protocollib.api;
 
+/**
+ * Representing the different protocol phases of a minecraft.
+ */
 public enum ProtocolPhase {
 
     HANDSHAKE, PLAY, STATUS, LOGIN, CONFIGURATION, UNKNOWN;

src/main/java/dev/protocollib/api/listener/AsyncPacketListener.java

@@ -0,0 +1,32 @@
+package dev.protocollib.api.listener;
+
+import dev.protocollib.api.PacketContainer;
+
+/**
+ * Functional interface for handling packets asynchronously.
+ * 
+ * <p>Once a packet is processed by the listener, the context's 
+ * {@code resumeProcessing()} or {@code resumeProcessingWithException(Throwable)} 
+ * methods must be called to signal that the listener is done with the packet.
+ * Failing to call one of these methods will cause the packet to remain in 
+ * a waiting state until it times out, preventing further listeners from 
+ * receiving the packet.
+ * </p>
+ */
+@FunctionalInterface
+public interface AsyncPacketListener {
+
+    /**
+     * Handles a packet that was sent or received, asynchronously.
+     *
+     * <p>Once processing is complete, ensure that one of the {@code resumeProcessing} 
+     * methods from the {@link AsyncPacketListenerContext} is called. This allows the 
+     * packet to continue to the next listener. If not called, the packet will remain 
+     * in a waiting state and will only proceed after a timeout occurs.</p>
+     *
+     * @param packet  the packet to handle
+     * @param context the context providing additional information about the packet and connection
+     */
+    void handlePacket(PacketContainer packet, AsyncPacketListenerContext context);
+
+}

src/main/java/dev/protocollib/api/listener/AsyncPacketListenerContext.java

@@ -0,0 +1,21 @@
+package dev.protocollib.api.listener;
+
+/**
+ * Representing the context of an asynchronous packet listener.
+ */
+public interface AsyncPacketListenerContext extends SyncPacketListenerContext {
+
+	/**
+	 * Singles the listener is done with processing the packet.
+	 */
+	void resumeProcessing();
+
+	/**
+	 * Singles the listener is done with processing the packet and finished
+	 * with an exception.
+	 * 
+	 * @param throwable the processing exception
+	 */
+	void resumeProcessingWithException(Throwable throwable);
+
+}