Update to use NotNullByDefault & Docs update

Update to v1.4.0

This also fixes redundant assignments and provides javadoc comments for side effects from null values least in BungeeProtocol.

Changes how requests Forward requires less than an unsigned short of length.

Adds tests for forward data length.

Adds static final for legacy/modern channels. Unsure if its required on any proxy to send from the non legacy one at this point.

Adds javadocs for ONLINE/ALL

Author: kermandev

build.gradle.kts

@@ -4,7 +4,7 @@ plugins {
 }
 
 group = "dev.kerman"
-version = "1.3.1"
+version = "1.4.0"
 
 repositories {
     mavenCentral()

src/main/java/dev/kerman/freight/BungeeMessage.java

@@ -7,7 +7,7 @@
 import net.minestom.server.network.packet.server.common.PluginMessagePacket;
 import net.minestom.server.network.player.PlayerConnection;
 import net.minestom.server.utils.PacketSendingUtils;
-import org.jetbrains.annotations.NotNull;
+import org.jetbrains.annotations.Contract;
 import org.jetbrains.annotations.Nullable;
 
 import java.util.ArrayList;
@@ -66,10 +66,22 @@
  * Some notes about this class include attempting to hide all the serialization implementation behind the protocol,
  * We still expose all the serializers for the requests and responses in case you want to use them, but don't expect them
  * to be stable, but they will probably be stable as the messaging system is likely to not change.
+ * <br>
+ * Assume all types to be without identity as these classes are going to be value types; which identity required operations may fail.
  */
 public sealed interface BungeeMessage permits BungeeRequest, BungeeResponse {
-    String ALL = "ALL";
-    String ONLINE = "ONLINE";
+    /**
+     * Represents the ALL identity
+     * <br>
+     * You should use the helper methods like {@link BungeeRequest.Forward#all(PluginMessagePacket)} where possible.
+     */
+    String ALL = BungeeProtocol.ALL;
+    /**
+     * Represents the ONLINE identity
+     * <br>
+     * You should use the helper methods like {@link BungeeRequest.Forward#online(PluginMessagePacket)} where possible.
+     */
+    String ONLINE = BungeeProtocol.ONLINE;
 
     /**
      * Checks if the given channel is a valid BungeeCord identifier.
@@ -83,6 +95,7 @@ public sealed interface BungeeMessage permits BungeeRequest, BungeeResponse {
      * @param channel the channel to check, can be null
      * @return true if the channel is a valid BungeeCord identifier, false otherwise
      */
+    @Contract(pure = true)
     static boolean isIdentifier(@Nullable String channel) {
         return BungeeProtocol.isIdentifier(channel);
     }
@@ -93,8 +106,10 @@ static boolean isIdentifier(@Nullable String channel) {
      *
      * @param message the message to write
      * @return the byte array containing the serialized message
+     * @throws NullPointerException if {@code message} is null
      */
-    static byte @NotNull [] write(@NotNull BungeeMessage message) {
+    @Contract(pure = true)
+    static byte[] write(BungeeMessage message) {
         Objects.requireNonNull(message, "Message cannot be null");
         return switch (message) {
             case BungeeRequest request -> writeRequest(request);
@@ -110,8 +125,10 @@ static boolean isIdentifier(@Nullable String channel) {
      *
      * @param request the request to write
      * @return the byte array containing the serialized request
+     * @throws NullPointerException if {@code request} is null
      */
-    static byte @NotNull [] writeRequest(@NotNull BungeeRequest request) {
+    @Contract(pure = true)
+    static byte[] writeRequest(BungeeRequest request) {
         Objects.requireNonNull(request, "Request cannot be null");
         return NetworkBuffer.makeArray(BungeeRequest.SERIALIZER, request);
     }
@@ -122,9 +139,11 @@ static boolean isIdentifier(@Nullable String channel) {
      *
      * @param bytes the byte array to read the request from
      * @return the request, never null
+     * @throws NullPointerException if {@code bytes} is null
      * @throws IllegalStateException if there are leftover bytes in the buffer after reading the request
      */
-    static @NotNull BungeeRequest readRequest(byte @NotNull [] bytes) throws IllegalStateException {
+    @Contract(pure = true)
+    static BungeeRequest readRequest(byte[] bytes) throws IllegalStateException {
         Objects.requireNonNull(bytes, "Bytes cannot be null!");
         return readRequest(NetworkBuffer.wrap(bytes, 0, bytes.length));
     }
@@ -135,9 +154,11 @@ static boolean isIdentifier(@Nullable String channel) {
      *
      * @param buffer the buffer to read the response from
      * @return the response, never null
+     * @throws NullPointerException if {@code buffer} is null
      * @throws IllegalStateException if there are leftover bytes in the buffer after reading the request
      */
-    static @NotNull BungeeRequest readRequest(@NotNull NetworkBuffer buffer) throws IllegalStateException {
+    @Contract(mutates = "param1")
+    static BungeeRequest readRequest(NetworkBuffer buffer) throws IllegalStateException {
         Objects.requireNonNull(buffer, "Buffer cannot be null!");
         return BungeeProtocol.read(buffer, BungeeRequest.SERIALIZER);
     }
@@ -149,8 +170,10 @@ static boolean isIdentifier(@Nullable String channel) {
      *
      * @param response the response to write
      * @return the byte array containing the serialized response
+     * @throws NullPointerException if {@code response} is null
      */
-    static byte @NotNull [] writeResponse(@NotNull BungeeResponse response) {
+    @Contract(pure = true)
+    static byte[] writeResponse(BungeeResponse response) {
         Objects.requireNonNull(response, "Response cannot be null");
         return NetworkBuffer.makeArray(BungeeResponse.SERIALIZER, response);
     }
@@ -160,9 +183,11 @@ static boolean isIdentifier(@Nullable String channel) {
      *
      * @param bytes the byte array to read the response from
      * @return the response, never null
+     * @throws NullPointerException if {@code bytes} is null
      * @throws IllegalStateException if there are leftover bytes in the buffer after reading the request
      */
-    static @NotNull BungeeResponse readResponse(byte @NotNull [] bytes) throws IllegalStateException {
+    @Contract(pure = true)
+    static BungeeResponse readResponse(byte[] bytes) throws IllegalStateException {
         Objects.requireNonNull(bytes, "Bytes cannot be null!");
         return readResponse(NetworkBuffer.wrap(bytes, 0, bytes.length));
     }
@@ -173,9 +198,11 @@ static boolean isIdentifier(@Nullable String channel) {
      *
      * @param buffer the buffer to read the response from
      * @return the response, never null
+     * @throws NullPointerException if {@code buffer} is null
      * @throws IllegalStateException if there are leftover bytes in the buffer after reading the request
      */
-    static @NotNull BungeeResponse readResponse(@NotNull NetworkBuffer buffer) throws IllegalStateException {
+    @Contract(mutates = "param1")
+    static BungeeResponse readResponse(NetworkBuffer buffer) throws IllegalStateException {
         Objects.requireNonNull(buffer, "Buffer cannot be null!");
         return BungeeProtocol.read(buffer, BungeeResponse.SERIALIZER);
     }
@@ -188,9 +215,11 @@ static boolean isIdentifier(@Nullable String channel) {
      *
      * @param event the event to read the response from
      * @return the response, or null if the event is not a BungeeCord message
+     * @throws NullPointerException if {@code event} is null
      * @throws IllegalStateException if there are leftover bytes in the buffer after reading the request
      */
-    static @Nullable BungeeResponse readResponse(@NotNull PlayerPluginMessageEvent event) throws IllegalStateException {
+    @Contract(pure = true)
+    static @Nullable BungeeResponse readResponse(PlayerPluginMessageEvent event) throws IllegalStateException {
         Objects.requireNonNull(event, "Event cannot be null");
         if (!isIdentifier(event.getIdentifier())) return null;
         return readResponse(event.getMessage());
@@ -205,8 +234,10 @@ static boolean isIdentifier(@Nullable String channel) {
      *
      * @param connection the player connection to send the message to
      * @param message    the message to send
+     * @throws NullPointerException if {@code connection} is null
+     * @throws NullPointerException if {@code message} is null
      */
-    static void send(@NotNull PlayerConnection connection, @NotNull BungeeMessage message) {
+    static void send(PlayerConnection connection, BungeeMessage message) {
         Objects.requireNonNull(connection, "Connection cannot be null");
         Objects.requireNonNull(message, "Message cannot be null");
         connection.sendPacket(message.toPacket());
@@ -220,8 +251,10 @@ static void send(@NotNull PlayerConnection connection, @NotNull BungeeMessage me
      *
      * @param audience the audience to send the message
      * @param message  the message to send
+     * @throws NullPointerException if {@code connection} is null
+     * @throws NullPointerException if {@code message} is null
      */
-    static void send(@NotNull Audience audience, @NotNull BungeeMessage message) {
+    static void send(Audience audience, BungeeMessage message) {
         Objects.requireNonNull(audience, "Audience cannot be null");
         Objects.requireNonNull(message, "Message cannot be null");
         PacketSendingUtils.sendPacket(audience, message.toPacket());
@@ -230,12 +263,16 @@ static void send(@NotNull Audience audience, @NotNull BungeeMessage message) {
     /**
      * Sends the message to a single audience from a collection of audiences.
      * <p>Shuffles the collection and sends the message to a random audience.</p>
+     * <br>
+     * Inherent's any side effects of {@link BungeeMessage#send(Audience, BungeeMessage)}
      *
      * @param audiences the collection of audiences to send the message to
      * @param message   the message to send
+     * @throws NullPointerException if {@code audiences} is null
+     * @throws NullPointerException if {@code message} is null
      * @throws IllegalArgumentException if the collection is empty
      */
-    static void sendSingle(@NotNull Collection<? extends Audience> audiences, @NotNull BungeeMessage message) {
+    static void sendSingle(Collection<? extends Audience> audiences, BungeeMessage message) {
         Objects.requireNonNull(audiences, "Audiences cannot be null");
         Objects.requireNonNull(message, "Message cannot be null");
         if (audiences.isEmpty()) throw new IllegalArgumentException("Audiences cannot be empty");
@@ -252,8 +289,9 @@ static void sendSingle(@NotNull Collection<? extends Audience> audiences, @NotNu
      *
      * @return the client plugin message packet containing the serialized message
      */
-    default @NotNull ClientPluginMessagePacket toClientPacket() {
-        return new ClientPluginMessagePacket(BungeeProtocol.CHANNEL, write(this));
+    @Contract(pure = true)
+    default ClientPluginMessagePacket toClientPacket() {
+        return new ClientPluginMessagePacket(BungeeProtocol.CHANNEL_LEGACY, write(this));
     }
 
     /**
@@ -264,8 +302,9 @@ static void sendSingle(@NotNull Collection<? extends Audience> audiences, @NotNu
      *
      * @return the plugin message packet containing the serialized message
      */
-    default @NotNull PluginMessagePacket toPacket() {
-        return new PluginMessagePacket(BungeeProtocol.CHANNEL, write(this));
+    @Contract(pure = true)
+    default PluginMessagePacket toPacket() {
+        return new PluginMessagePacket(BungeeProtocol.CHANNEL_LEGACY, write(this));
     }
 
     /**
@@ -276,8 +315,9 @@ static void sendSingle(@NotNull Collection<? extends Audience> audiences, @NotNu
      * </p>
      *
      * @param connection the player connection to send the message to
+     * @throws NullPointerException if {@code connection} is null
      */
-    default void send(@NotNull PlayerConnection connection) {
+    default void send(PlayerConnection connection) {
         Objects.requireNonNull(connection, "Connection cannot be null");
         BungeeMessage.send(connection, this);
     }
@@ -289,8 +329,9 @@ default void send(@NotNull PlayerConnection connection) {
      * </p>
      *
      * @param audience the audience to send the message
+     * @throws NullPointerException if {@code audience} is null
      */
-    default void send(@NotNull Audience audience) {
+    default void send(Audience audience) {
         Objects.requireNonNull(audience, "Audience cannot be null");
         BungeeMessage.send(audience, this);
     }
@@ -302,9 +343,10 @@ default void send(@NotNull Audience audience) {
      * </p>
      *
      * @param audiences the collection of audiences to send the message to
+     * @throws NullPointerException if {@code audiences} is null
      * @throws IllegalArgumentException if the collection is empty
      */
-    default void sendSingle(@NotNull Collection<? extends Audience> audiences) {
+    default void sendSingle(Collection<? extends Audience> audiences) {
         Objects.requireNonNull(audiences, "Audience cannot be null");
         if (audiences.isEmpty()) throw new IllegalArgumentException("Audiences cannot be empty");
         BungeeMessage.sendSingle(audiences, this);

src/main/java/dev/kerman/freight/BungeeProtocol.java

@@ -2,10 +2,10 @@
 
 import net.minestom.server.network.NetworkBuffer;
 import net.minestom.server.network.NetworkBufferTemplate;
-import org.jetbrains.annotations.NotNull;
 import org.jetbrains.annotations.Nullable;
 
 import java.util.List;
+import java.util.Objects;
 import java.util.UUID;
 
 /**
@@ -17,7 +17,10 @@
  * The protocol is used to communicate between the server and BungeeCord proxy.
  */
 final class BungeeProtocol {
-    static final String CHANNEL = "BungeeCord"; // aka bungeecord:main
+    static final String ALL = "ALL";
+    static final String ONLINE = "ONLINE";
+    static final String CHANNEL_MODERN = "bungeecord:main";
+    static final String CHANNEL_LEGACY = "BungeeCord";
     static final NetworkBuffer.Type<List<String>> CSV_TYPE = NetworkBuffer.STRING_IO_UTF8.transform(
             string -> List.of(string.split(",")),
             stringList -> String.join(",", stringList)
@@ -31,15 +34,15 @@ final class BungeeProtocol {
     static final NetworkBuffer.Type<byte[]> SHORT_BYTE_ARRAY_TYPE = new NetworkBuffer.Type<>() {
         // Reminder that they use big endian for IO, so we should be good as the protocol uses it too
         @Override
-        public void write(@NotNull NetworkBuffer buffer, byte @NotNull [] value) {
+        public void write(NetworkBuffer buffer, byte[] value) {
             final int length = value.length;
             if (length > 65535) throw new IllegalStateException("Value too long");
             buffer.write(NetworkBuffer.UNSIGNED_SHORT, length);
             buffer.write(NetworkBuffer.FixedRawBytes(length), value);
         }
 
         @Override
-        public byte[] read(@NotNull NetworkBuffer buffer) {
+        public byte[] read(NetworkBuffer buffer) {
             final int length = buffer.read(NetworkBuffer.UNSIGNED_SHORT);
             if (length > 65535) throw new IllegalStateException("Value too long");
             if (buffer.readableBytes() > length) throw new IllegalStateException("Value too long to read");
@@ -48,11 +51,11 @@ public byte[] read(@NotNull NetworkBuffer buffer) {
     };
 
     static boolean isIdentifier(@Nullable String channel) {
-        return CHANNEL.equals(channel) || "bungeecord:main".equals(channel);
+        return CHANNEL_LEGACY.equals(channel) || CHANNEL_MODERN.equals(channel);
     }
 
     // Reads the message from the buffer and checks if there are any leftover bytes
-    static <T extends BungeeMessage> T read(@NotNull NetworkBuffer buffer, NetworkBuffer.@NotNull Type<T> type) throws IllegalStateException {
+    static <T extends BungeeMessage> T read(NetworkBuffer buffer, NetworkBuffer.Type<T> type) throws IllegalStateException {
         final T read = buffer.read(type);
         final long readableBytes = buffer.readableBytes();
         if (readableBytes > 0) throw new IllegalStateException("%s message not fully read! %d bytes left over.".formatted(read.getClass().getName(), readableBytes));
@@ -89,13 +92,13 @@ enum Type {
         // Sometimes unprefixed, so we need to handle that.
         public static final NetworkBuffer.Type<Type> RESPONSE_SERIALIZER = new NetworkBuffer.Type<>() {
             @Override
-            public void write(@NotNull NetworkBuffer buffer, Type value) {
+            public void write(NetworkBuffer buffer, Type value) {
                 if (value == Forward || value == ForwardToPlayer) return; // These are unprefixed, so we don't write the name.
                 buffer.write(NetworkBuffer.STRING_IO_UTF8, value.name());
             }
 
             @Override
-            public Type read(@NotNull NetworkBuffer buffer) {
+            public Type read(NetworkBuffer buffer) {
                 final long readIndex = buffer.readIndex();
                 try { // Try to determine if the type is prefixed or not.
                     final String name = buffer.read(NetworkBuffer.STRING_IO_UTF8);
@@ -108,16 +111,16 @@ public Type read(@NotNull NetworkBuffer buffer) {
         };
 
         private final NetworkBuffer.Type<? extends BungeeRequest> requestSerializer;
-        private final NetworkBuffer.Type<? extends BungeeResponse> responseSerializer;
+        private final NetworkBuffer.@Nullable Type<? extends BungeeResponse> responseSerializer;
 
-        Type(NetworkBuffer.Type<? extends BungeeRequest> requestSerializer, NetworkBuffer.Type<? extends BungeeResponse> responseSerializer) {
+        Type(NetworkBuffer.Type<? extends BungeeRequest> requestSerializer, NetworkBuffer.@Nullable Type<? extends BungeeResponse> responseSerializer) {
             this.requestSerializer = requestSerializer;
             this.responseSerializer = responseSerializer;
         }
 
         // Could probably use polymorphism here, but it makes the classes have less information about the serialization
         // See the entries in the regular ClientPacket and ServerPacket not caring about the id near the data structure.
-        static @NotNull Type toType(@NotNull BungeeMessage message) {
+        static Type toType(BungeeMessage message) {
             return switch (message) {
                 // Requests
                 case BungeeRequest.Connect ignored -> Connect;
@@ -154,7 +157,7 @@ public Type read(@NotNull NetworkBuffer buffer) {
         }
 
         public NetworkBuffer.Type<? extends BungeeResponse> responseSerializer() {
-            return responseSerializer;
+            return Objects.requireNonNull(responseSerializer, "Response serializer must not be null");
         }
 
         public NetworkBuffer.Type<? extends BungeeRequest> requestSerializer() {