feat(api): add basic packet processing interfaces

Author: Ingrim4

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/PacketDirection.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();
 
 }