refactor: replace string delimiter wire format with JSON envelope

Swofty · claude · Swofty · commit 6a62d8e30eba · 2026-04-19T20:39:39.000+10:00
Co-Authored-By: Claude Opus 4.6 (1M context) &lt;noreply@anthropic.com&gt;
diff --git a/commons/build.gradle.kts b/commons/build.gradle.kts
@@ -15,6 +15,7 @@ java {
 }
 
 dependencies {
+    implementation(libs.json)
     implementation(libs.snakeyaml)
     implementation(project(":packer"))
     implementation(libs.mongodb.bson)
diff --git a/commons/src/main/java/net/swofty/commons/redis/RedisEnvelope.java b/commons/src/main/java/net/swofty/commons/redis/RedisEnvelope.java
@@ -0,0 +1,22 @@
+package net.swofty.commons.redis;
+
+import org.json.JSONObject;
+
+public record RedisEnvelope(String id, String from, String payload) {
+    public String serialize() {
+        JSONObject json = new JSONObject();
+        json.put("id", id);
+        json.put("from", from);
+        json.put("payload", payload);
+        return json.toString();
+    }
+
+    public static RedisEnvelope deserialize(String json) {
+        JSONObject obj = new JSONObject(json);
+        return new RedisEnvelope(
+                obj.getString("id"),
+                obj.getString("from"),
+                obj.optString("payload", "")
+        );
+    }
+}
diff --git a/docs/superpowers/specs/2026-04-19-service-comms-phase2-design.md b/docs/superpowers/specs/2026-04-19-service-comms-phase2-design.md
@@ -0,0 +1,60 @@
+# Service Communication Phase 2 - Design Spec
+
+## Goal
+
+Complete the typed service communication refactor: migrate Path C (proxy channels), replace fragile string delimiter wire format, annotate remaining polymorphic event hierarchies for Jackson, and add standardized error handling.
+
+## 1. Path C Migration
+
+Replace `ToProxyChannels`/`FromProxyChannels` enums + `ProxyChannelRequirements` + raw JSONObject with typed `ProtocolObject` subclasses using `JacksonSerializer`.
+
+### To-Proxy Channels (11 channels, game server -> proxy)
+
+Each becomes a `ProtocolObject<Request, Response>` in `commons/.../protocol/objects/proxy/to/`. The velocity.extension `@ChannelListener` handler gets typed request/response instead of JSONObject.
+
+### From-Proxy Channels (8 channels, proxy -> game server)
+
+Each becomes a `ProtocolObject<Request, Response>` in `commons/.../protocol/objects/proxy/from/`. The `ProxyToClient` interface is replaced by a typed equivalent.
+
+### Deletion targets
+
+- `ToProxyChannels` enum
+- `FromProxyChannels` enum
+- `ProxyChannelRequirements` abstract class
+- All 20 requirements classes in `commons/.../proxy/requirements/to/` and `from/`
+- `ProxyToClient` interface
+- All old `ProxyToClient` implementations (8 files)
+
+## 2. Wire Format
+
+Replace all `}=-=-={` and `}=-=---={` string delimiter framing with a JSON envelope.
+
+### Envelope format
+
+```json
+{"id":"<uuid>","from":"<sender-filter-id>","payload":"<serialized-content>"}
+```
+
+### Files to change (6 core transport files)
+
+- `proxy.api/.../redis/ServerOutboundMessage.java` - sends to proxy + receives from service
+- `proxy.api/.../ProxyAPI.java` - receives from proxy + receives from service
+- `velocity.extension/.../redis/RedisListener.java` - receives from server, sends response
+- `velocity.extension/.../redis/RedisMessage.java` - sends to server, receives response
+- `service.generic/.../ServiceInitializer.java` - receives from server, sends response
+- `service.generic/.../redis/ServiceToServerManager.java` - sends to server, receives response
+- `service.punishment/.../ProxyRedis.java` - sends to proxy
+
+## 3. Remaining Hand-Written Serializers
+
+Add Jackson polymorphism annotations to `PartyEvent` (30 subclasses) and `FriendEvent` (24 subclasses) hierarchies, then swap `SendPartyEventToServiceProtocolObject` and `SendFriendEventToServiceProtocolObject` to `JacksonSerializer`.
+
+### Approach
+
+- Add `@JsonTypeInfo(use = Id.NAME)` + `@JsonSubTypes({...})` to `PartyEvent` and `FriendEvent` base classes
+- Add `@JsonCreator` to each subclass constructor
+- Replace hand-written serializers with `JacksonSerializer` in the two ProtocolObjects
+
+## 4. Standardized Error Envelope
+
+Not adding a `Result<T>` wrapper -- it would require changing every single protocol response type and every call site. Instead, standardize on a convention: every Response record should have `boolean success` and `@Nullable String error` fields. This is already the pattern used by most protocols. Audit and fix the few that don't follow it.
diff --git a/proxy.api/src/main/java/net/swofty/proxyapi/ProxyAPI.java b/proxy.api/src/main/java/net/swofty/proxyapi/ProxyAPI.java
@@ -1,6 +1,7 @@
 package net.swofty.proxyapi;
 
 import net.swofty.commons.protocol.ServicePushProtocol;
+import net.swofty.commons.redis.RedisEnvelope;
 import net.swofty.proxyapi.redis.ProxyToClient;
 import net.swofty.proxyapi.redis.TypedServiceHandler;
 import net.swofty.redisapi.api.ChannelRegistry;
@@ -22,10 +23,10 @@ public ProxyAPI(String URI, UUID serverUUID) {
 
     public void registerFromProxyHandler(ProxyToClient handler) {
         RedisAPI.getInstance().registerChannel(handler.getChannel().getChannelName(), (event) -> {
-            String[] split = event.message.split("}=-=-=\\{");
-            UUID request = UUID.fromString(split[0].substring(split[0].indexOf(";") + 1));
-            String rawMessage = split[1];
-            JSONObject json = new JSONObject(rawMessage);
+            String messageWithoutFilter = event.message.substring(event.message.indexOf(";") + 1);
+            RedisEnvelope envelope = RedisEnvelope.deserialize(messageWithoutFilter);
+            UUID request = UUID.fromString(envelope.id());
+            JSONObject json = new JSONObject(envelope.payload());
 
             JSONObject response = handler.onMessage(json);
 
@@ -37,7 +38,7 @@ public void registerFromProxyHandler(ProxyToClient handler) {
             RedisAPI.getInstance().publishMessage(
                     "proxy",
                     ChannelRegistry.getFromName(handler.getChannel().getChannelName()),
-                    request + "}=-=-={" + response.toString());
+                    new RedisEnvelope(envelope.id(), serverUUID.toString(), response.toString()).serialize());
         });
     }
 
@@ -46,10 +47,11 @@ public <T, R> void registerTypedServiceHandler(TypedServiceHandler<T, R> handler
         String channelName = "service_" + protocol.channel();
 
         RedisAPI.getInstance().registerChannel(channelName, (event) -> {
-            String[] split = event.message.split("}=-=-=\\{");
-            String serviceId = split[0].substring(split[0].indexOf(";") + 1);
-            UUID requestId = UUID.fromString(split[1]);
-            String rawMessage = split[2];
+            String messageWithoutFilter = event.message.substring(event.message.indexOf(";") + 1);
+            RedisEnvelope envelope = RedisEnvelope.deserialize(messageWithoutFilter);
+            String serviceId = envelope.from();
+            UUID requestId = UUID.fromString(envelope.id());
+            String rawMessage = envelope.payload();
 
             Thread.startVirtualThread(() -> {
                 T typedMessage = protocol.translateFromString(rawMessage);
@@ -60,15 +62,16 @@ public <T, R> void registerTypedServiceHandler(TypedServiceHandler<T, R> handler
                 RedisAPI.getInstance().publishMessage(
                         serviceId,
                         ChannelRegistry.getFromName("service_response"),
-                        requestId + "}=-=-={" + serializedResponse);
+                        new RedisEnvelope(envelope.id(), serverUUID.toString(), serializedResponse).serialize());
             });
         });
 
         RedisAPI.getInstance().registerChannel("service_broadcast_" + protocol.channel(), (event) -> {
-            String[] split = event.message.split("}=-=-=\\{");
-            String serviceId = split[0].substring(split[0].indexOf(";") + 1);
-            UUID requestId = UUID.fromString(split[1]);
-            String rawMessage = split[2];
+            String messageWithoutFilter = event.message.substring(event.message.indexOf(";") + 1);
+            RedisEnvelope envelope = RedisEnvelope.deserialize(messageWithoutFilter);
+            String serviceId = envelope.from();
+            UUID requestId = UUID.fromString(envelope.id());
+            String rawMessage = envelope.payload();
 
             Thread.startVirtualThread(() -> {
                 T typedMessage = protocol.translateFromString(rawMessage);
@@ -81,7 +84,7 @@ public <T, R> void registerTypedServiceHandler(TypedServiceHandler<T, R> handler
                 RedisAPI.getInstance().publishMessage(
                         serviceId,
                         ChannelRegistry.getFromName("service_broadcast_response"),
-                        requestId + "}=-=-={" + serverUUID.toString() + "}=-=-={" + serializedResponse);
+                        new RedisEnvelope(envelope.id(), serverUUID.toString(), serializedResponse).serialize());
             });
         });
     }
diff --git a/proxy.api/src/main/java/net/swofty/proxyapi/redis/ServerOutboundMessage.java b/proxy.api/src/main/java/net/swofty/proxyapi/redis/ServerOutboundMessage.java
@@ -4,6 +4,7 @@
 import net.swofty.commons.impl.ServiceProxyRequest;
 import net.swofty.commons.protocol.ProtocolObject;
 import net.swofty.commons.proxy.ToProxyChannels;
+import net.swofty.commons.redis.RedisEnvelope;
 import net.swofty.redisapi.api.ChannelRegistry;
 import net.swofty.redisapi.api.RedisAPI;
 import org.json.JSONObject;
@@ -24,10 +25,10 @@ public static void registerServerToProxy(ToProxyChannels channel) {
         RedisAPI.getInstance().registerChannel(channel.getChannelName(), (event) -> {
             String messageWithoutFilter = event.message.substring(event.message.indexOf(";") + 1);
 
-            String[] split = messageWithoutFilter.split("}=-=-=\\{");
-            UUID uuid = UUID.fromString(split[0]);
+            RedisEnvelope envelope = RedisEnvelope.deserialize(messageWithoutFilter);
+            UUID uuid = UUID.fromString(envelope.id());
 
-            redisMessageListeners.get(uuid).accept(split[1]);
+            redisMessageListeners.get(uuid).accept(envelope.payload());
             redisMessageListeners.remove(uuid);
         });
     }
@@ -43,7 +44,7 @@ public static void sendMessageToProxy(ToProxyChannels channel, JSONObject messag
 
         RedisAPI.getInstance().publishMessage("proxy",
                 ChannelRegistry.getFromName(channel.getChannelName()),
-                message.toString() + "}=-=-={" + uuid + "}=-=-={" + filterID);
+                new RedisEnvelope(uuid.toString(), filterID.toString(), message.toString()).serialize());
     }
 
     public static void registerFromProtocolObject(ProtocolObject object) {
@@ -52,13 +53,10 @@ public static void registerFromProtocolObject(ProtocolObject object) {
 
         RedisAPI.getInstance().registerChannel(object.channel(), (event) -> {
             String messageWithoutFilter = event.message.substring(event.message.indexOf(";") + 1);
-            String[] split = messageWithoutFilter.split("}=-=---=\\{");
 
-            UUID uuid = UUID.fromString(split[0]);
-            String message;
-            if (split.length != 1) {
-                message = split[1];
-            } else message = "";
+            RedisEnvelope envelope = RedisEnvelope.deserialize(messageWithoutFilter);
+            UUID uuid = UUID.fromString(envelope.id());
+            String message = envelope.payload();
 
             try {
                 redisMessageListeners.get(uuid).accept(message);
diff --git a/service.generic/src/main/java/net/swofty/service/generic/ServiceInitializer.java b/service.generic/src/main/java/net/swofty/service/generic/ServiceInitializer.java
@@ -3,6 +3,7 @@
 import lombok.RequiredArgsConstructor;
 import net.swofty.commons.config.ConfigProvider;
 import net.swofty.commons.impl.ServiceProxyRequest;
+import net.swofty.commons.redis.RedisEnvelope;
 import net.swofty.commons.skyblock.item.attribute.ItemAttribute;
 import net.swofty.commons.protocol.ProtocolObject;
 import net.swofty.redisapi.api.ChannelRegistry;
@@ -52,7 +53,7 @@ public void init() {
 
                     RedisAPI.getInstance().publishMessage(request.getRequestServer(),
                             ChannelRegistry.getFromName(request.getEndpoint()),
-                            request.getRequestId() + "}=-=---={" + response).join();
+                            new RedisEnvelope(request.getRequestId().toString(), service.getType().name(), response).serialize()).join();
                 });
             });
         });
diff --git a/service.generic/src/main/java/net/swofty/service/generic/redis/ServiceToServerManager.java b/service.generic/src/main/java/net/swofty/service/generic/redis/ServiceToServerManager.java
@@ -2,6 +2,7 @@
 
 import net.swofty.commons.ServiceType;
 import net.swofty.commons.protocol.ServicePushProtocol;
+import net.swofty.commons.redis.RedisEnvelope;
 import net.swofty.commons.protocol.objects.data.GetPlayerDataPushProtocol;
 import net.swofty.commons.protocol.objects.data.LockPlayerDataPushProtocol;
 import net.swofty.commons.protocol.objects.data.UnlockPlayerDataPushProtocol;
@@ -36,25 +37,25 @@ public static void initialize(ServiceType serviceType) {
 
         // Register response handler for server responses
         RedisAPI.getInstance().registerChannel("service_response", (event) -> {
-            String[] split = event.message.split("}=-=-=\\{");
-            UUID requestId = UUID.fromString(split[0].substring(split[0].indexOf(";") + 1));
-            String response = split[1];
+            String messageWithoutFilter = event.message.substring(event.message.indexOf(";") + 1);
+            RedisEnvelope envelope = RedisEnvelope.deserialize(messageWithoutFilter);
+            UUID requestId = UUID.fromString(envelope.id());
 
             CompletableFuture<JSONObject> future = pendingRequests.remove(requestId);
             if (future != null) {
-                future.complete(new JSONObject(response));
+                future.complete(new JSONObject(envelope.payload()));
             }
         });
 
         RedisAPI.getInstance().registerChannel("service_broadcast_response", (event) -> {
-            String[] split = event.message.split("}=-=-=\\{");
-            UUID requestId = UUID.fromString(split[0].substring(split[0].indexOf(";") + 1));
-            UUID serverUUID = UUID.fromString(split[1]);
-            String response = split[2];
+            String messageWithoutFilter = event.message.substring(event.message.indexOf(";") + 1);
+            RedisEnvelope envelope = RedisEnvelope.deserialize(messageWithoutFilter);
+            UUID requestId = UUID.fromString(envelope.id());
+            UUID serverUUID = UUID.fromString(envelope.from());
 
             BroadcastRequest broadcastRequest = pendingBroadcastRequests.get(requestId);
             if (broadcastRequest != null) {
-                broadcastRequest.addResponse(serverUUID, new JSONObject(response));
+                broadcastRequest.addResponse(serverUUID, new JSONObject(envelope.payload()));
             }
         });
     }
@@ -90,12 +91,11 @@ public static <T, R> CompletableFuture<R> sendToServer(
 
         String serialized = protocol.translateToString(message);
         String channelName = "service_" + protocol.channel();
-        String messageContent = currentServiceType.name() + "}=-=-={" + requestId + "}=-=-={" + serialized;
 
         RedisAPI.getInstance().publishMessage(
                 serverUUID.toString(),
                 ChannelRegistry.getFromName(channelName),
-                messageContent
+                new RedisEnvelope(requestId.toString(), currentServiceType.name(), serialized).serialize()
         );
 
         return future;
@@ -115,13 +115,10 @@ public static <T, R> CompletableFuture<Map<UUID, R>> sendToAllServers(
 
         String serialized = protocol.translateToString(message);
         String channelName = "service_broadcast_" + protocol.channel();
-        String messageContent = currentServiceType.name()
-                + "}=-=-={" + requestId
-                + "}=-=-={" + serialized;
 
         RedisAPI.getInstance().publishMessage("all",
                 ChannelRegistry.getFromName(channelName),
-                messageContent);
+                new RedisEnvelope(requestId.toString(), currentServiceType.name(), serialized).serialize());
 
         scheduler.schedule(() -> {
             BroadcastRequest req = pendingBroadcastRequests.remove(requestId);
diff --git a/service.punishment/src/main/java/net/swofty/service/punishment/ProxyRedis.java b/service.punishment/src/main/java/net/swofty/service/punishment/ProxyRedis.java
@@ -5,6 +5,7 @@
 import redis.clients.jedis.JedisPoolConfig;
 
 import net.swofty.commons.proxy.ToProxyChannels;
+import net.swofty.commons.redis.RedisEnvelope;
 import org.json.JSONObject;
 
 import java.net.URI;
@@ -66,7 +67,7 @@ public static CompletableFuture<Void> publishMessage(String filterId, String cha
     public static void publishToProxy(ToProxyChannels channel, JSONObject message) {
         UUID uuid = UUID.randomUUID();
         publishMessage("proxy", channel.getChannelName(),
-                message.toString() + "}=-=-={" + uuid + "}=-=-={" + uuid);
+                new RedisEnvelope(uuid.toString(), uuid.toString(), message.toString()).serialize());
     }
 
     public static boolean isInitialized() {
diff --git a/velocity.extension/src/main/java/net/swofty/velocity/redis/RedisListener.java b/velocity.extension/src/main/java/net/swofty/velocity/redis/RedisListener.java
@@ -1,5 +1,6 @@
 package net.swofty.velocity.redis;
 
+import net.swofty.commons.redis.RedisEnvelope;
 import net.swofty.redisapi.api.ChannelRegistry;
 import net.swofty.redisapi.api.RedisAPI;
 import org.json.JSONObject;
@@ -17,28 +18,26 @@ public RedisListener() {
     }
 
     public void onMessage(String channel, String message) {
-        String[] split = message.split("}=-=-=\\{");
-        String rawMessage = split[0];
-        UUID uuid = UUID.fromString(split[1]);
-        UUID filterID = UUID.fromString(split[2]);
-
-        String messageWithoutFilter = rawMessage.substring(rawMessage.indexOf(";") + 1);
-        JSONObject json = new JSONObject(messageWithoutFilter);
+        String messageWithoutFilter = message.substring(message.indexOf(";") + 1);
+        RedisEnvelope envelope = RedisEnvelope.deserialize(messageWithoutFilter);
+        UUID uuid = UUID.fromString(envelope.id());
+        UUID filterID = UUID.fromString(envelope.from());
+        JSONObject json = new JSONObject(envelope.payload());
 
         Thread.startVirtualThread(() -> {
             JSONObject response;
             try {
                 response = receivedMessage(json, filterID);
             } catch (Exception e) {
-                System.out.println("Error on channel " + channel + " with message " + messageWithoutFilter);
+                System.out.println("Error on channel " + channel + " with message " + envelope.payload());
                 Logger.error(e, "Error in Redis listener");
                 return;
             }
 
             RedisAPI.getInstance().publishMessage(
                     filterID.toString(),
                     ChannelRegistry.getFromName(channel),
-                    uuid + "}=-=-={" + response.toString());
+                    new RedisEnvelope(envelope.id(), "proxy", response.toString()).serialize());
         });
     }
 
diff --git a/velocity.extension/src/main/java/net/swofty/velocity/redis/RedisMessage.java b/velocity.extension/src/main/java/net/swofty/velocity/redis/RedisMessage.java
@@ -1,6 +1,7 @@
 package net.swofty.velocity.redis;
 
 import net.swofty.commons.proxy.FromProxyChannels;
+import net.swofty.commons.redis.RedisEnvelope;
 import net.swofty.redisapi.api.ChannelRegistry;
 import net.swofty.redisapi.api.RedisAPI;
 import org.json.JSONObject;
@@ -24,16 +25,17 @@ public static CompletableFuture<JSONObject> sendMessageToServer(UUID server,
         RedisAPI.getInstance().publishMessage(
                 server.toString(),
                 ChannelRegistry.getFromName(channel.getChannelName()),
-                requestID + "}=-=-={" + message.toString());
+                new RedisEnvelope(requestID.toString(), "proxy", message.toString()).serialize());
 
         return future;
     }
 
     public static void registerProxyToServer(FromProxyChannels channel) {
         RedisAPI.getInstance().registerChannel(channel.getChannelName(), (event) -> {
-            String[] split = event.message.split("}=-=-=\\{");
-            UUID request = UUID.fromString(split[0].substring(split[0].indexOf(";") + 1));
-            String rawMessage = split[1];
+            String messageWithoutFilter = event.message.substring(event.message.indexOf(";") + 1);
+            RedisEnvelope envelope = RedisEnvelope.deserialize(messageWithoutFilter);
+            UUID request = UUID.fromString(envelope.id());
+            String rawMessage = envelope.payload();
 
             try {
                 callbacks.get(request).complete(new JSONObject(rawMessage));

Original file line number	Diff line number	Diff line change
`@@ -15,6 +15,7 @@ java {`
`15`	`15`	`}`
`16`	`16`
`17`	`17`	`dependencies {`
	`18`	`+ implementation(libs.json)`
`18`	`19`	`implementation(libs.snakeyaml)`
`19`	`20`	`implementation(project(":packer"))`
`20`	`21`	`implementation(libs.mongodb.bson)`