[ECO-5139] feat: add action and serial fields

lib/src/main/java/io/ably/lib/realtime/ChannelBase.java

@@ -25,6 +25,7 @@
 import io.ably.lib.types.DeltaExtras;
 import io.ably.lib.types.ErrorInfo;
 import io.ably.lib.types.Message;
+import io.ably.lib.types.MessageAction;
 import io.ably.lib.types.MessageDecodeException;
 import io.ably.lib.types.MessageSerializer;
 import io.ably.lib.types.PaginatedResult;
@@ -843,6 +844,12 @@ private void onMessage(final ProtocolMessage protocolMessage) {
             if(msg.connectionId == null) msg.connectionId = protocolMessage.connectionId;
             if(msg.timestamp == 0) msg.timestamp = protocolMessage.timestamp;
             if(msg.id == null) msg.id = protocolMessage.id + ':' + i;
+            // (TM2p)
+            if(msg.version == null) msg.version = String.format("%s:%03d", protocolMessage.channelSerial, i);
+            // (TM2k)
+            if(msg.serial == null && msg.action == MessageAction.MESSAGE_CREATE) msg.serial = msg.version;
+            // (TM2o)
+            if(msg.createdAt == null && msg.action == MessageAction.MESSAGE_CREATE) msg.createdAt = msg.timestamp;
 
             try {
                 msg.decode(options, decodingContext);

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

@@ -278,6 +278,20 @@ protected Long readLong(final JsonObject map, final String key) {
         return element.getAsLong();
     }
 
+    /**
+     * Read an optional numerical value.
+     * @return The value, or null if the key was not present in the map.
+     * @throws ClassCastException if an element exists for that key and that element is not a {@link JsonPrimitive}
+     * or is not a valid int value.
+     */
+    protected Integer readInt(final JsonObject map, final String key) {
+        final JsonElement element = map.get(key);
+        if (null == element || element instanceof JsonNull) {
+            return null;
+        }
+        return element.getAsInt();
+    }
+
     /* Msgpack processing */
     boolean readField(MessageUnpacker unpacker, String fieldName, MessageFormat fieldType) throws IOException {
         boolean result = true;

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

@@ -46,9 +46,41 @@ public class Message extends BaseMessage {
      */
     public String connectionKey;
 
+    /**
+     * (TM2k) serial string – an opaque string that uniquely identifies the message. If a message received from Ably
+     * (whether over realtime or REST, eg history) with an action of MESSAGE_CREATE does not contain a serial,
+     * the SDK must set it equal to its version.
+     */
+    public String serial;
+
+    /**
+     * (TM2p) version string – an opaque string that uniquely identifies the message, and is different for different versions.
+     * If a message received from Ably over a realtime transport does not contain a version,
+     * the SDK must set it to <channelSerial>:<padded_index> from the channelSerial field of the enclosing ProtocolMessage,
+     * and padded_index is the index of the message inside the messages array of the ProtocolMessage,
+     * left-padded with 0s to three digits (for example, the second entry might be foo:001)
+     */
+    public String version;
+
+    /**
+     * (TM2j) action enum
+     */
+    public MessageAction action;
+
+    /**
+     * (TM2o) createdAt time in milliseconds since epoch. If a message received from Ably
+     * (whether over realtime or REST, eg history) with an action of MESSAGE_CREATE does not contain a createdAt,
+     * the SDK must set it equal to the TM2f timestamp.
+     */
+    public Long createdAt;
+
     private static final String NAME = "name";
     private static final String EXTRAS = "extras";
     private static final String CONNECTION_KEY = "connectionKey";
+    private static final String SERIAL = "serial";
+    private static final String VERSION = "version";
+    private static final String ACTION = "action";
+    private static final String CREATED_AT = "createdAt";
 
     /**
      * Default constructor
@@ -128,6 +160,10 @@ void writeMsgpack(MessagePacker packer) throws IOException {
         int fieldCount = super.countFields();
         if(name != null) ++fieldCount;
         if(extras != null) ++fieldCount;
+        if(serial != null) ++fieldCount;
+        if(version != null) ++fieldCount;
+        if(action != null) ++fieldCount;
+        if(createdAt != null) ++fieldCount;
         packer.packMapHeader(fieldCount);
         super.writeFields(packer);
         if(name != null) {
@@ -138,6 +174,22 @@ void writeMsgpack(MessagePacker packer) throws IOException {
             packer.packString(EXTRAS);
             extras.write(packer);
         }
+        if(serial != null) {
+            packer.packString(SERIAL);
+            packer.packString(serial);
+        }
+        if(version != null) {
+            packer.packString(VERSION);
+            packer.packString(version);
+        }
+        if(action != null) {
+            packer.packString(ACTION);
+            packer.packInt(action.ordinal());
+        }
+        if(createdAt != null) {
+            packer.packString(CREATED_AT);
+            packer.packLong(createdAt);
+        }
     }
 
     Message readMsgpack(MessageUnpacker unpacker) throws IOException {
@@ -157,6 +209,14 @@ Message readMsgpack(MessageUnpacker unpacker) throws IOException {
                 name = unpacker.unpackString();
             } else if (fieldName.equals(EXTRAS)) {
                 extras = MessageExtras.read(unpacker);
+            } else if (fieldName.equals(SERIAL)) {
+                serial = unpacker.unpackString();
+            } else if (fieldName.equals(VERSION)) {
+                version = unpacker.unpackString();
+            } else if (fieldName.equals(ACTION)) {
+                action = MessageAction.tryFindByOrdinal(unpacker.unpackInt());
+            } else if (fieldName.equals(CREATED_AT)) {
+                createdAt = unpacker.unpackLong();
             } else {
                 Log.v(TAG, "Unexpected field: " + fieldName);
                 unpacker.skipValue();
@@ -313,6 +373,12 @@ protected void read(final JsonObject map) throws MessageDecodeException {
             }
             extras = MessageExtras.read((JsonObject) extrasElement);
         }
+
+        serial = readString(map, SERIAL);
+        version = readString(map, VERSION);
+        Integer actionOrdinal = readInt(map, ACTION);
+        action = actionOrdinal == null ? null : MessageAction.tryFindByOrdinal(actionOrdinal);
+        createdAt = readLong(map, CREATED_AT);
     }
 
     public static class Serializer implements JsonSerializer<Message>, JsonDeserializer<Message> {
@@ -328,6 +394,18 @@ public JsonElement serialize(Message message, Type typeOfMessage, JsonSerializat
             if (message.connectionKey != null) {
                 json.addProperty(CONNECTION_KEY, message.connectionKey);
             }
+            if (message.serial != null) {
+                json.addProperty(SERIAL, message.serial);
+            }
+            if (message.version != null) {
+                json.addProperty(VERSION, message.version);
+            }
+            if (message.action != null) {
+                json.addProperty(ACTION, message.action.ordinal());
+            }
+            if (message.createdAt != null) {
+                json.addProperty(CREATED_AT, message.createdAt);
+            }
             return json;
         }
 

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

@@ -0,0 +1,15 @@
+package io.ably.lib.types;
+
+public enum MessageAction {
+    MESSAGE_UNSET, // 0
+    MESSAGE_CREATE, // 1
+    MESSAGE_UPDATE, // 2
+    MESSAGE_DELETE, // 3
+    ANNOTATION_CREATE, // 4
+    ANNOTATION_DELETE, // 5
+    META_OCCUPANCY; // 6
+
+    static MessageAction tryFindByOrdinal(int ordinal) {
+        return values().length <= ordinal ? null: values()[ordinal];
+    }
+}

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

@@ -3,6 +3,8 @@
 import static org.junit.Assert.assertArrayEquals;
 import static org.junit.Assert.assertEquals;
 import static org.junit.Assert.assertNotEquals;
+import static org.junit.Assert.assertNotNull;
+import static org.junit.Assert.assertNull;
 import static org.junit.Assert.assertTrue;
 import static org.junit.Assert.fail;
 
@@ -17,7 +19,9 @@
 import com.google.gson.JsonElement;
 import com.google.gson.JsonObject;
 import com.google.gson.JsonPrimitive;
+import io.ably.lib.types.MessageAction;
 import io.ably.lib.types.MessageExtras;
+import io.ably.lib.types.Param;
 import io.ably.lib.util.Serialisation;
 import org.junit.Ignore;
 import org.junit.Rule;
@@ -970,4 +974,40 @@ public void opaque_message_extras() throws AblyException {
             }
         }
     }
+
+    /**
+     * Check that important chat SDK fields are populated (serial, action, createdAt)
+     */
+    @Test
+    public void should_have_serial_action_createdAt() throws AblyException {
+        ClientOptions opts = createOptions(testVars.keys[7].keyStr);
+        opts.clientId = "chat";
+        try (AblyRealtime realtime = new AblyRealtime(opts)) {
+            final Channel channel = realtime.channels.get("foo::$chat::$chatMessages");
+            CompletionWaiter msgComplete = new CompletionWaiter();
+            channel.subscribe(message -> {
+                assertNotNull(message.serial);
+                assertNotNull(message.version);
+                assertNotNull(message.createdAt);
+                assertEquals(MessageAction.MESSAGE_CREATE, message.action);
+                assertEquals("chat.message", message.name);
+                assertEquals("hello world!", ((JsonObject)message.data).get("text").getAsString());
+                msgComplete.onSuccess();
+            });
+
+            /* publish to the channel */
+            JsonObject chatMessage = new JsonObject();
+            chatMessage.addProperty("text", "hello world!");
+            realtime.request(
+                "POST",
+                "/chat/v2/rooms/foo/messages",
+                new Param[] { new Param("v", 3) },
+                HttpUtils.requestBodyFromGson(chatMessage, opts.useBinaryProtocol),
+                null
+            );
+
+            // wait until we get message on the channel
+            assertNull(msgComplete.waitFor(1, 10_000));
+        }
+    }
 }

lib/src/test/java/io/ably/lib/types/MessageTest.java

@@ -46,4 +46,69 @@ public void serialize_message_with_name_and_data() {
         assertEquals("test-data", serializedObject.get("data").getAsString());
         assertEquals("test-name", serializedObject.get("name").getAsString());
     }
+
+    @Test
+    public void serialize_message_with_serial() {
+        // Given
+        Message message = new Message("test-name", "test-data");
+        message.clientId = "test-client-id";
+        message.connectionKey = "test-key";
+        message.action = MessageAction.MESSAGE_CREATE;
+        message.serial = "01826232498871-001@abcdefghij:001";
+
+        // When
+        JsonElement serializedElement = serializer.serialize(message, null, null);
+
+        // Then
+        JsonObject serializedObject = serializedElement.getAsJsonObject();
+        assertEquals("test-client-id", serializedObject.get("clientId").getAsString());
+        assertEquals("test-key", serializedObject.get("connectionKey").getAsString());
+        assertEquals("test-data", serializedObject.get("data").getAsString());
+        assertEquals("test-name", serializedObject.get("name").getAsString());
+        assertEquals(1, serializedObject.get("action").getAsInt());
+        assertEquals("01826232498871-001@abcdefghij:001", serializedObject.get("serial").getAsString());
+    }
+
+    @Test
+    public void deserialize_message_with_serial() throws Exception {
+        // Given
+       JsonObject jsonObject = new JsonObject();
+       jsonObject.addProperty("clientId", "test-client-id");
+       jsonObject.addProperty("data", "test-data");
+       jsonObject.addProperty("name", "test-name");
+       jsonObject.addProperty("action", 1);
+       jsonObject.addProperty("serial", "01826232498871-001@abcdefghij:001");
+
+        // When
+        Message message = Message.fromEncoded(jsonObject, new ChannelOptions());
+
+        // Then
+        assertEquals("test-client-id", message.clientId);
+        assertEquals("test-data", message.data);
+        assertEquals("test-name", message.name);
+        assertEquals(MessageAction.MESSAGE_CREATE, message.action);
+        assertEquals("01826232498871-001@abcdefghij:001", message.serial);
+    }
+
+
+    @Test
+    public void deserialize_message_with_unknown_action() throws Exception {
+        // Given
+        JsonObject jsonObject = new JsonObject();
+        jsonObject.addProperty("clientId", "test-client-id");
+        jsonObject.addProperty("data", "test-data");
+        jsonObject.addProperty("name", "test-name");
+        jsonObject.addProperty("action", 10);
+        jsonObject.addProperty("serial", "01826232498871-001@abcdefghij:001");
+
+        // When
+        Message message = Message.fromEncoded(jsonObject, new ChannelOptions());
+
+        // Then
+        assertEquals("test-client-id", message.clientId);
+        assertEquals("test-data", message.data);
+        assertEquals("test-name", message.name);
+        assertNull(message.action);
+        assertEquals("01826232498871-001@abcdefghij:001", message.serial);
+    }
 }

lib/src/test/resources/local/testAppSpec.json

@@ -19,8 +19,11 @@
 		},
 		{
 			"capability": "{\"persisted:text_protocol:channel0\":[\"publish\",\"subscribe\",\"history\"],\"persisted:text_protocol:channel1\":[\"publish\",\"subscribe\",\"history\"],\"persisted:binary_protocol:channel0\":[\"publish\",\"subscribe\",\"history\"],\"persisted:binary_protocol:channel1\":[\"publish\",\"subscribe\",\"history\"],\"persisted:*\":[\"subscribe\",\"history\"]}"
-		}
-	],
+		},
+    {
+      "capability": "{ \"[*]*\":[\"*\"] }"
+    }
+  ],
 	"namespaces": [
 		{
 			"id": "persisted",
@@ -78,4 +81,4 @@
 			]
 		}
 	]
-}
+}