feat: implement protocol v4 support for enhanced message annotations and versioning

Introduce `MessageAnnotations` and `MessageVersion` classes for protocol v4. Replace `summary` with `annotations` in `Message`. Enhance version tracking with detailed metadata, ensuring compatibility with the new protocol. Update tests and protocol version to `4`.

Author: ttypic

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

@@ -29,9 +29,9 @@
 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.MessageVersion;
 import io.ably.lib.types.PaginatedResult;
 import io.ably.lib.types.Param;
 import io.ably.lib.types.PresenceMessage;
@@ -901,10 +901,10 @@ 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;
-            // (TM2k)
-            if(msg.serial == null && msg.version != null && msg.action == MessageAction.MESSAGE_CREATE) msg.serial = msg.version;
-            // (TM2o)
-            if(msg.createdAt == null && msg.action == MessageAction.MESSAGE_CREATE) msg.createdAt = msg.timestamp;
+            // (TM2s1)
+            if(msg.version == null) msg.version = new MessageVersion(msg.serial, msg.timestamp);
+            if(msg.version.serial == null) msg.version.serial = msg.serial;
+            if(msg.version.timestamp == 0) msg.version.timestamp = msg.timestamp;
 
             try {
                 if (msg.data != null) msg.decode(options, decodingContext);

lib/src/main/java/io/ably/lib/transport/Defaults.java

@@ -12,7 +12,7 @@ public class Defaults {
      * spec: G4
      * </p>
      */
-    public static final String ABLY_PROTOCOL_VERSION = "2";
+    public static final String ABLY_PROTOCOL_VERSION = "4";
 
     public static final String ABLY_AGENT_VERSION   = String.format("%s/%s", "ably-java", BuildConfig.VERSION);
 

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

@@ -3,8 +3,6 @@
 import java.io.IOException;
 import java.lang.reflect.Type;
 import java.util.Collection;
-import java.util.HashMap;
-import java.util.Map;
 
 import com.google.gson.JsonArray;
 import com.google.gson.JsonDeserializer;
@@ -50,143 +48,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
+     * (TM2r) 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.
+     * (TM2s) version object – enhanced version tracking for Protocol v4.
+     * Contains detailed version metadata including serial and timestamp information.
      * (May not be populated depending on app & channel namespace settings)
      */
-    public String version;
+    public MessageVersion 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;
-
-    /**
-     * (TM2l) ref string – an opaque string that uniquely identifies some referenced message.
-     */
-    public String refSerial;
-
-    /**
-     * (TM2m) refType string – an opaque string that identifies the type of this reference.
-     */
-    public String refType;
-
-    /**
-     * (TM2n) operation object – data object that may contain the `optional` attributes.
-     */
-    public Operation operation;
-
     /**
      * (TM2q) A summary of all the annotations that have been made to the message, whose keys are the `type` fields
      * from any annotations that it includes. Will always be populated for a message with action {@code MESSAGE_SUMMARY},
      * and may be populated for any other type (in particular a message retrieved from
      * REST history will have its latest summary included).
      */
-    public Summary summary;
-
-    public static class Operation {
-        public String clientId;
-        public String description;
-        public Map<String, String> metadata;
+    public MessageAnnotations annotations;
 
-        void write(MessagePacker packer) throws IOException {
-            int fieldCount = 0;
-            if (clientId != null) fieldCount++;
-            if (description != null) fieldCount++;
-            if (metadata != null) fieldCount++;
 
-            packer.packMapHeader(fieldCount);
-
-            if (clientId != null) {
-                packer.packString("clientId");
-                packer.packString(clientId);
-            }
-            if (description != null) {
-                packer.packString("description");
-                packer.packString(description);
-            }
-            if (metadata != null) {
-                packer.packString("metadata");
-                packer.packMapHeader(metadata.size());
-                for (Map.Entry<String, String> entry : metadata.entrySet()) {
-                    packer.packString(entry.getKey());
-                    packer.packString(entry.getValue());
-                }
-            }
-        }
-
-        protected static Operation read(final MessageUnpacker unpacker) throws IOException {
-            Operation operation = new Operation();
-            int fieldCount = unpacker.unpackMapHeader();
-            for (int i = 0; i < fieldCount; i++) {
-                String fieldName = unpacker.unpackString().intern();
-                switch (fieldName) {
-                    case "clientId":
-                        operation.clientId = unpacker.unpackString();
-                        break;
-                    case "description":
-                        operation.description = unpacker.unpackString();
-                        break;
-                    case "metadata":
-                        int mapSize = unpacker.unpackMapHeader();
-                        operation.metadata = new HashMap<>(mapSize);
-                        for (int j = 0; j < mapSize; j++) {
-                            String key = unpacker.unpackString();
-                            String value = unpacker.unpackString();
-                            operation.metadata.put(key, value);
-                        }
-                        break;
-                    default:
-                        unpacker.skipValue();
-                        break;
-                }
-            }
-            return operation;
-        }
-
-        protected static Operation read(final JsonObject jsonObject) throws MessageDecodeException {
-            Operation operation = new Operation();
-            if (jsonObject.has("clientId")) {
-                operation.clientId = jsonObject.get("clientId").getAsString();
-            }
-            if (jsonObject.has("description")) {
-                operation.description = jsonObject.get("description").getAsString();
-            }
-            if (jsonObject.has("metadata")) {
-                JsonObject metadataObject = jsonObject.getAsJsonObject("metadata");
-                operation.metadata = new HashMap<>();
-                for (Map.Entry<String, JsonElement> entry : metadataObject.entrySet()) {
-                    operation.metadata.put(entry.getKey(), entry.getValue().getAsString());
-                }
-            }
-            return operation;
-        }
-    }
 
     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";
-    private static final String REF_SERIAL = "refSerial";
-    private static final String REF_TYPE = "refType";
-    private static final String OPERATION = "operation";
-    private static final String SUMMARY = "summary";
+    private static final String ANNOTATIONS = "annotations";
 
     /**
      * Default constructor
@@ -270,11 +166,7 @@ void writeMsgpack(MessagePacker packer) throws IOException {
         if(serial != null) ++fieldCount;
         if(version != null) ++fieldCount;
         if(action != null) ++fieldCount;
-        if(createdAt != null) ++fieldCount;
-        if(refSerial != null) ++fieldCount;
-        if(refType != null) ++fieldCount;
-        if(operation != null) ++fieldCount;
-        if(summary != null) ++fieldCount;
+        if(annotations != null) ++fieldCount;
 
         packer.packMapHeader(fieldCount);
         super.writeFields(packer);
@@ -296,31 +188,15 @@ void writeMsgpack(MessagePacker packer) throws IOException {
         }
         if(version != null) {
             packer.packString(VERSION);
-            packer.packString(version);
+            version.writeMsgpack(packer);
         }
         if(action != null) {
             packer.packString(ACTION);
             packer.packInt(action.ordinal());
         }
-        if(createdAt != null) {
-            packer.packString(CREATED_AT);
-            packer.packLong(createdAt);
-        }
-        if(refSerial != null) {
-            packer.packString(REF_SERIAL);
-            packer.packString(refSerial);
-        }
-        if(refType != null) {
-            packer.packString(REF_TYPE);
-            packer.packString(refType);
-        }
-        if(operation != null) {
-            packer.packString(OPERATION);
-            operation.write(packer);
-        }
-        if(summary != null) {
-            packer.packString(SUMMARY);
-            summary.write(packer);
+        if(annotations != null) {
+            packer.packString(ANNOTATIONS);
+            annotations.writeMsgpack(packer);
         }
     }
 
@@ -346,19 +222,11 @@ Message readMsgpack(MessageUnpacker unpacker) throws IOException {
             } else if (fieldName.equals(SERIAL)) {
                 serial = unpacker.unpackString();
             } else if (fieldName.equals(VERSION)) {
-                version = unpacker.unpackString();
+                version = MessageVersion.fromMsgpack(unpacker);
             } else if (fieldName.equals(ACTION)) {
                 action = MessageAction.tryFindByOrdinal(unpacker.unpackInt());
-            } else if (fieldName.equals(CREATED_AT)) {
-                createdAt = unpacker.unpackLong();
-            }  else if (fieldName.equals(REF_SERIAL)) {
-                refSerial = unpacker.unpackString();
-            } else if (fieldName.equals(REF_TYPE)) {
-                refType = unpacker.unpackString();
-            } else if (fieldName.equals(OPERATION)) {
-                operation = Operation.read(unpacker);
-            } else if (fieldName.equals(SUMMARY)) {
-                summary = Summary.read(unpacker);
+            } else if (fieldName.equals(ANNOTATIONS)) {
+                annotations = MessageAnnotations.fromMsgpack(unpacker);
             }
             else {
                 Log.v(TAG, "Unexpected field: " + fieldName);
@@ -519,27 +387,18 @@ protected void read(final JsonObject map) throws MessageDecodeException {
         connectionKey = readString(map, CONNECTION_KEY);
 
         serial = readString(map, SERIAL);
-        version = readString(map, VERSION);
+
+        // Handle version field - supports both legacy string format and new MessageVersion object format
+        final JsonElement versionElement = map.get(VERSION);
+        if (versionElement != null) {
+            version = MessageVersion.read(versionElement);
+        }
         Integer actionOrdinal = readInt(map, ACTION);
         action = actionOrdinal == null ? null : MessageAction.tryFindByOrdinal(actionOrdinal);
-        createdAt = readLong(map, CREATED_AT);
-        refSerial = readString(map, REF_SERIAL);
-        refType = readString(map, REF_TYPE);
-
-        final JsonElement operationElement = map.get(OPERATION);
-        if (null != operationElement) {
-            if (!operationElement.isJsonObject()) {
-                throw MessageDecodeException.fromDescription("Message operation is of type \"" + operationElement.getClass() + "\" when expected a JSON object.");
-            }
-            operation = Operation.read(operationElement.getAsJsonObject());
-        }
 
-        final JsonElement summaryElement = map.get(SUMMARY);
-        if (summaryElement != null) {
-            if (!summaryElement.isJsonObject()) {
-                throw MessageDecodeException.fromDescription("Message summary is of type \"" + summaryElement.getClass() + "\" when expected a JSON object.");
-            }
-            summary = Summary.read(summaryElement.getAsJsonObject());
+        final JsonElement annotationsElement = map.get(ANNOTATIONS);
+        if (annotationsElement != null) {
+            annotations = MessageAnnotations.read(annotationsElement);
         }
     }
 
@@ -560,25 +419,13 @@ public JsonElement serialize(Message message, Type typeOfMessage, JsonSerializat
                 json.addProperty(SERIAL, message.serial);
             }
             if (message.version != null) {
-                json.addProperty(VERSION, message.version);
+                json.add(VERSION, message.version.toJsonTree());
             }
             if (message.action != null) {
                 json.addProperty(ACTION, message.action.ordinal());
             }
-            if (message.createdAt != null) {
-                json.addProperty(CREATED_AT, message.createdAt);
-            }
-            if (message.refSerial != null) {
-                json.addProperty(REF_SERIAL, message.refSerial);
-            }
-            if (message.refType != null) {
-                json.addProperty(REF_TYPE, message.refType);
-            }
-            if (message.operation != null) {
-                json.add(OPERATION, Serialisation.gson.toJsonTree(message.operation));
-            }
-            if (message.summary != null) {
-                json.add(SUMMARY, message.summary.toJsonTree());
+            if (message.annotations != null) {
+                json.add(ANNOTATIONS, message.annotations.toJsonTree());
             }
             return json;
         }