feat: add Java custom payload bridge sender

Author: bb-dev

src/main/java/org/itxtech/synapseapi/java/JavaCustomPayloadBridge.java

@@ -0,0 +1,31 @@
+package org.itxtech.synapseapi.java;
+
+import org.itxtech.synapseapi.SynapsePlayer;
+import org.itxtech.synapseapi.multiprotocol.protocol11810.protocol.ScriptMessagePacket11810;
+
+import java.util.Objects;
+import java.util.Optional;
+
+/**
+ * Java 客户端自定义载荷的双向桥接入口。
+ */
+public final class JavaCustomPayloadBridge {
+
+    private JavaCustomPayloadBridge() {
+    }
+
+    public static boolean send(final SynapsePlayer player, final String channel, final byte[] payload) {
+        Objects.requireNonNull(player, "player");
+        if (!player.isOnline() || !player.isJavaClient()) {
+            return false;
+        }
+        final Optional<String> encoded = JavaCustomPayloadEnvelope.encode(channel, payload);
+        if (encoded.isEmpty()) {
+            return false;
+        }
+        final ScriptMessagePacket11810 packet = new ScriptMessagePacket11810();
+        packet.messageId = JavaCustomPayloadEnvelope.SCRIPT_MESSAGE_ID;
+        packet.value = encoded.get();
+        return player.dataPacket(packet);
+    }
+}

src/main/java/org/itxtech/synapseapi/java/JavaCustomPayloadEnvelope.java

@@ -7,16 +7,17 @@
 import java.util.Arrays;
 import java.util.Base64;
 import java.util.Optional;
+import java.util.regex.Pattern;
 
 /**
- * ViaBedrock 输出的受限 Java 自定义载荷信封解码器。
- * 与商业功能解耦，插件收到通用事件后自行决定是否处理频道。
+ * ViaBedrock 双向 Java 自定义载荷桥的 ScriptMessage 信封编解码器。
  */
 public final class JavaCustomPayloadEnvelope {
 
     public static final String SCRIPT_MESSAGE_ID = "easecation:java_custom_payload_v1";
     public static final int MAX_CHANNEL_BYTES = 128;
     public static final int MAX_PAYLOAD_BYTES = 8 * 1024;
+    private static final Pattern CHANNEL_PATTERN = Pattern.compile("[a-z0-9_.-]+:[a-z0-9/._-]+");
 
     private JavaCustomPayloadEnvelope() {
     }
@@ -52,6 +53,21 @@ public static Optional<Payload> decode(final String messageId, final String enco
         }
     }
 
+    public static Optional<String> encode(final String channel, final byte[] payload) {
+        if (channel == null || payload == null || !CHANNEL_PATTERN.matcher(channel).matches()) {
+            return Optional.empty();
+        }
+        final byte[] channelBytes = channel.getBytes(StandardCharsets.UTF_8);
+        if (channelBytes.length == 0 || channelBytes.length > MAX_CHANNEL_BYTES || payload.length > MAX_PAYLOAD_BYTES) {
+            return Optional.empty();
+        }
+        final byte[] envelope = new byte[1 + channelBytes.length + payload.length];
+        envelope[0] = (byte) channelBytes.length;
+        System.arraycopy(channelBytes, 0, envelope, 1, channelBytes.length);
+        System.arraycopy(payload, 0, envelope, 1 + channelBytes.length, payload.length);
+        return Optional.of(Base64.getUrlEncoder().withoutPadding().encodeToString(envelope));
+    }
+
     private static boolean isUnpaddedBase64Url(String value) {
         if (value == null || value.isEmpty()) {
             return false;

src/test/java/org/itxtech/synapseapi/java/JavaCustomPayloadEnvelopeTest.java

@@ -32,6 +32,19 @@ void decodesOnlyTheFixedBridgeEnvelopeAndDefensivelyCopiesPayload() {
         assertFalse(JavaCustomPayloadEnvelope.decode("other:message", "AA").isPresent());
     }
 
+    @Test
+    void encodesTheSameEnvelopeThatTheDecoderAccepts() {
+        byte[] payload = new byte[]{2, 1, 0, -1};
+
+        String encoded = JavaCustomPayloadEnvelope.encode("easecation:launcher_commerce", payload).orElseThrow();
+        JavaCustomPayloadEnvelope.Payload decoded = JavaCustomPayloadEnvelope.decode(
+                JavaCustomPayloadEnvelope.SCRIPT_MESSAGE_ID, encoded).orElseThrow();
+
+        assertEquals("easecation:launcher_commerce", decoded.channel());
+        assertArrayEquals(payload, decoded.payload());
+        assertTrue(JavaCustomPayloadEnvelope.encode("invalid channel", payload).isEmpty());
+    }
+
     @Test
     void rejectsMalformedOrOverLimitEnvelopes() {
         byte[] malformedUtf8 = new byte[]{1, -1};