feat: add extras field to PresenceMessage (TP3i)

Add extras field to PresenceMessage type with support for both
msgpack and JSON serialization/deserialization. Includes end-to-end
test verifying extras round-trip through presence enter.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: AndyTWF

lib/src/main/java/io/ably/lib/types/PresenceMessage.java

@@ -75,6 +75,16 @@ public enum Action {
      */
     public Action action;
 
+    /**
+     * A MessageExtras object of arbitrary key-value pairs that may contain metadata, and/or ancillary payloads.
+     * Valid payloads include {@link DeltaExtras}, {@link JsonObject}.
+     * <p>
+     * Spec: TP3i
+     */
+    public MessageExtras extras;
+
+    private static final String EXTRAS = "extras";
+
     /**
      * Default constructor
      */
@@ -123,16 +133,22 @@ public Object clone() {
         result.encoding = encoding;
         result.data = data;
         result.action = action;
+        result.extras = extras;
         return result;
     }
 
     void writeMsgpack(MessagePacker packer) throws IOException {
         int fieldCount = super.countFields();
         ++fieldCount;
+        if(extras != null) ++fieldCount;
         packer.packMapHeader(fieldCount);
         super.writeFields(packer);
         packer.packString("action");
         packer.packInt(action.getValue());
+        if(extras != null) {
+            packer.packString(EXTRAS);
+            extras.write(packer);
+        }
     }
 
     PresenceMessage readMsgpack(MessageUnpacker unpacker) throws IOException {
@@ -145,6 +161,8 @@ PresenceMessage readMsgpack(MessageUnpacker unpacker) throws IOException {
             if(super.readField(unpacker, fieldName, fieldFormat)) { continue; }
             if(fieldName.equals("action")) {
                 action = Action.findByValue(unpacker.unpackInt());
+            } else if (fieldName.equals(EXTRAS)) {
+                extras = MessageExtras.read(unpacker);
             } else {
                 Log.v(TAG, "Unexpected field: " + fieldName);
                 unpacker.skipValue();
@@ -260,6 +278,24 @@ public static PresenceMessage[] fromEncodedArray(String presenceMsgArray, Channe
         }
     }
 
+    @Override
+    protected void read(final JsonObject map) throws MessageDecodeException {
+        super.read(map);
+
+        final JsonElement extrasElement = map.get(EXTRAS);
+        if (null != extrasElement) {
+            if (!(extrasElement instanceof JsonObject)) {
+                throw MessageDecodeException.fromDescription("PresenceMessage extras is of type \"" + extrasElement.getClass() + "\" when expected a JSON object.");
+            }
+            extras = MessageExtras.read((JsonObject) extrasElement);
+        }
+
+        Integer actionValue = readInt(map, "action");
+        if (actionValue != null) {
+            action = Action.findByValue(actionValue);
+        }
+    }
+
     public static class ActionSerializer implements JsonDeserializer<Action> {
         @Override
         public Action deserialize(JsonElement json, Type t, JsonDeserializationContext ctx)
@@ -268,13 +304,32 @@ public Action deserialize(JsonElement json, Type t, JsonDeserializationContext c
         }
     }
 
-    public static class Serializer implements JsonSerializer<PresenceMessage> {
+    public static class Serializer implements JsonSerializer<PresenceMessage>, JsonDeserializer<PresenceMessage> {
         @Override
         public JsonElement serialize(PresenceMessage message, Type typeOfMessage, JsonSerializationContext ctx) {
             final JsonObject json = BaseMessage.toJsonObject(message);
             if(message.action != null) json.addProperty("action", message.action.getValue());
+            if(message.extras != null) {
+                json.add(EXTRAS, Serialisation.gson.toJsonTree(message.extras));
+            }
             return json;
         }
+
+        @Override
+        public PresenceMessage deserialize(JsonElement json, Type typeOfT, JsonDeserializationContext context) throws JsonParseException {
+            if (!(json instanceof JsonObject)) {
+                throw new JsonParseException("Expected an object but got \"" + json.getClass() + "\".");
+            }
+
+            final PresenceMessage message = new PresenceMessage();
+            try {
+                message.read((JsonObject) json);
+            } catch (MessageDecodeException e) {
+                Log.e(TAG, e.getMessage(), e);
+                throw new JsonParseException("Failed to deserialize PresenceMessage from JSON.", e);
+            }
+            return message;
+        }
     }
 
     /**

lib/src/test/java/io/ably/lib/test/realtime/RealtimePresenceTest.java

@@ -3625,6 +3625,79 @@ public void messages_from_encoded_json_array() throws AblyException {
         }
     }
 
+    /**
+     * Enter presence with extras field and verify it comes back on the other side
+     * Test TP3i
+     */
+    @Test
+    public void presence_enter_with_extras() {
+        AblyRealtime clientAbly1 = null;
+        TestChannel testChannel = new TestChannel();
+        try {
+            /* subscribe for presence events in the anonymous connection */
+            PresenceWaiter presenceWaiter = new PresenceWaiter(testChannel.realtimeChannel);
+            /* set up a connection with specific clientId */
+            ClientOptions client1Opts = new ClientOptions() {{
+                tokenDetails = token1;
+                clientId = testClientId1;
+            }};
+            fillInOptions(client1Opts);
+            clientAbly1 = new AblyRealtime(client1Opts);
+
+            /* wait until connected */
+            (new ConnectionWaiter(clientAbly1.connection)).waitFor(ConnectionState.connected);
+            assertEquals("Verify connected state reached", clientAbly1.connection.state, ConnectionState.connected);
+
+            /* get channel and attach */
+            Channel client1Channel = clientAbly1.channels.get(testChannel.channelName);
+            client1Channel.attach();
+            (new ChannelWaiter(client1Channel)).waitFor(ChannelState.attached);
+            assertEquals("Verify attached state reached", client1Channel.state, ChannelState.attached);
+
+            /* create extras with headers.foo */
+            JsonObject extrasJson = new JsonObject();
+            JsonObject headers = new JsonObject();
+            headers.addProperty("foo", "bar");
+            extrasJson.add("headers", headers);
+            io.ably.lib.types.MessageExtras extras = new io.ably.lib.types.MessageExtras(extrasJson);
+
+            /* create presence message with extras */
+            String enterString = "Test data (presence_enter_with_extras)";
+            PresenceMessage presenceMsg = new PresenceMessage(PresenceMessage.Action.enter, null, enterString);
+            presenceMsg.extras = extras;
+
+            /* let client1 enter the channel with extras and wait for the entered event to be delivered */
+            CompletionWaiter enterComplete = new CompletionWaiter();
+            client1Channel.presence.updatePresence(presenceMsg, enterComplete);
+            presenceWaiter.waitFor(testClientId1, Action.enter);
+            PresenceMessage receivedMessage = presenceWaiter.contains(testClientId1, Action.enter);
+            assertNotNull("Verify presence message received", receivedMessage);
+            assertEquals("Verify data matches", enterString, receivedMessage.data);
+
+            /* verify extras field is present and correct */
+            assertNotNull("Verify extras is not null", receivedMessage.extras);
+            JsonObject receivedExtrasJson = receivedMessage.extras.asJsonObject();
+            assertNotNull("Verify extras JSON is not null", receivedExtrasJson);
+            assertTrue("Verify headers exists in extras", receivedExtrasJson.has("headers"));
+            JsonObject receivedHeaders = receivedExtrasJson.getAsJsonObject("headers");
+            assertNotNull("Verify headers object is not null", receivedHeaders);
+            assertTrue("Verify foo exists in headers", receivedHeaders.has("foo"));
+            assertEquals("Verify foo value matches", "bar", receivedHeaders.get("foo").getAsString());
+
+            /* verify enter callback called on completion */
+            enterComplete.waitFor();
+            assertTrue("Verify enter callback called on completion", enterComplete.success);
+        } catch(AblyException e) {
+            e.printStackTrace();
+            fail("Unexpected exception running test: " + e.getMessage());
+        } finally {
+            if(clientAbly1 != null)
+                clientAbly1.close();
+            if(testChannel != null)
+                testChannel.dispose();
+        }
+    }
+
     static class MessagesData {
         public PresenceMessage[] messages;
     }