[ECO-5642] feat: add message editing support to channels

- Introduced APIs to retrieve, update, and delete messages by serial identifier.
- Added support for fetching historical versions of messages.
- Implemented `MessageEditsMixin` to handle message editing operations.
- Added tests for message editing and retrieval functionality.

Author: ttypic

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

@@ -16,6 +16,7 @@
 import io.ably.lib.http.HttpUtils;
 import io.ably.lib.objects.RealtimeObjects;
 import io.ably.lib.objects.LiveObjectsPlugin;
+import io.ably.lib.rest.MessageEditsMixin;
 import io.ably.lib.rest.RestAnnotations;
 import io.ably.lib.transport.ConnectionManager;
 import io.ably.lib.transport.ConnectionManager.QueuedMessage;
@@ -100,6 +101,8 @@ public abstract class ChannelBase extends EventEmitter<ChannelEvent, ChannelStat
 
     @Nullable private final LiveObjectsPlugin liveObjectsPlugin;
 
+    private final MessageEditsMixin messageEditsMixin;
+
     public RealtimeObjects getObjects() throws AblyException {
         if (liveObjectsPlugin == null) {
             throw AblyException.fromErrorInfo(
@@ -1172,6 +1175,121 @@ else if(!"false".equalsIgnoreCase(param.value)) {
     private static final String KEY_UNTIL_ATTACH = "untilAttach";
     private static final String KEY_FROM_SERIAL = "fromSerial";
 
+    //region Message Edits and Deletes
+
+    /**
+     * Retrieves the latest version of a specific message by its serial identifier.
+     * <p>
+     * This method allows you to fetch the current state of a message, including any updates
+     * or deletions that have been applied since its creation.
+     *
+     * @param serial The unique serial identifier of the message to retrieve.
+     * @return A {@link Message} object representing the latest version of the message.
+     * @throws AblyException If the message cannot be retrieved or does not exist.
+     */
+    public Message getMessage(String serial) throws AblyException {
+        return messageEditsMixin.getMessage(ably.http, serial);
+    }
+
+    /**
+     * Asynchronously retrieves the latest version of a specific message by its serial identifier.
+     *
+     * @param serial The unique serial identifier of the message to retrieve.
+     * @param callback A callback to handle the result asynchronously.
+     * <p>
+     * This callback is invoked on a background thread.
+     */
+    public void getMessageAsync(String serial, Callback<Message> callback) {
+        messageEditsMixin.getMessageAsync(ably.http, serial, callback);
+    }
+
+    /**
+     * Updates an existing message by its serial identifier using patch semantics.
+     * <p>
+     * Non-null fields in the provided message (name, data, extras) will replace the corresponding
+     * fields in the existing message, while null fields will be left unchanged.
+     *
+     * @param serial The unique serial identifier of the message to update.
+     * @param message A {@link Message} object containing the fields to update.
+     *                Only non-null fields will be applied to the existing message.
+     * @throws AblyException If the update operation fails.
+     */
+    public void updateMessage(String serial, Message message) throws AblyException {
+        messageEditsMixin.updateMessage(ably.http, serial, message);
+    }
+
+    /**
+     * Asynchronously updates an existing message by its serial identifier.
+     *
+     * @param serial The unique serial identifier of the message to update.
+     * @param message A {@link Message} object containing the fields to update.
+     * @param listener A listener to be notified of the outcome of this operation.
+     * <p>
+     * This listener is invoked on a background thread.
+     */
+    public void updateMessageAsync(String serial, Message message, CompletionListener listener) {
+        messageEditsMixin.updateMessageAsync(ably.http, serial, message, listener);
+    }
+
+    /**
+     * Marks a message as deleted by its serial identifier.
+     * <p>
+     * This operation does not remove the message from history; it marks it as deleted
+     * while preserving the full message history. The deleted message can still be
+     * retrieved and will have its action set to MESSAGE_DELETE.
+     *
+     * @param serial The unique serial identifier of the message to delete.
+     * @param message A {@link Message} object that may contain operation metadata such as
+     *                clientId, description, or metadata in the version field.
+     * @throws AblyException If the delete operation fails.
+     */
+    public void deleteMessage(String serial, Message message) throws AblyException {
+        messageEditsMixin.deleteMessage(ably.http, serial, message);
+    }
+
+    /**
+     * Asynchronously marks a message as deleted by its serial identifier.
+     *
+     * @param serial The unique serial identifier of the message to delete.
+     * @param message A {@link Message} object for operation metadata.
+     * @param listener A listener to be notified of the outcome of this operation.
+     * <p>
+     * This listener is invoked on a background thread.
+     */
+    public void deleteMessageAsync(String serial, Message message, CompletionListener listener) {
+        messageEditsMixin.deleteMessageAsync(ably.http, serial, message, listener);
+    }
+
+    /**
+     * Retrieves all historical versions of a specific message.
+     * <p>
+     * This method returns a paginated result containing all versions of the message,
+     * ordered chronologically. Each version includes metadata about when and by whom
+     * the message was modified.
+     *
+     * @param serial The unique serial identifier of the message.
+     * @param params Query parameters for filtering or pagination (e.g., limit, start, end).
+     * @return A {@link PaginatedResult} containing an array of {@link Message} objects
+     *         representing all versions of the message.
+     * @throws AblyException If the versions cannot be retrieved.
+     */
+    public PaginatedResult<Message> getMessageVersions(String serial, Param[] params) throws AblyException {
+        return messageEditsMixin.getMessageVersions(ably.http, serial, params);
+    }
+
+    /**
+     * Asynchronously retrieves all historical versions of a specific message.
+     *
+     * @param serial The unique serial identifier of the message.
+     * @param params Query parameters for filtering or pagination.
+     * @param callback A callback to handle the result asynchronously.
+     */
+    public void getMessageVersionsAsync(String serial, Param[] params, Callback<AsyncPaginatedResult<Message>> callback) throws AblyException {
+        messageEditsMixin.getMessageVersionsAsync(ably.http, serial, params, callback);
+    }
+
+    //endregion
+
     /************************************
      * Channel history
      ************************************/
@@ -1353,6 +1471,7 @@ else if(stateChange.current.equals(failureState)) {
             this,
             new RestAnnotations(name, ably.http, ably.options, options)
         );
+        this.messageEditsMixin = new MessageEditsMixin(basePath, ably.options, options, ably.auth);
     }
 
     void onChannelMessage(ProtocolMessage msg) {

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

@@ -10,13 +10,17 @@
 import io.ably.lib.types.AsyncPaginatedResult;
 import io.ably.lib.types.Callback;
 import io.ably.lib.types.ChannelOptions;
+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;
 import io.ably.lib.types.Param;
 import io.ably.lib.types.PresenceMessage;
 import io.ably.lib.types.PresenceSerializer;
 import io.ably.lib.util.Crypto;
+import io.ably.lib.util.Serialisation;
 
 /**
  * A class representing a Channel in the Ably REST API.
@@ -45,13 +49,15 @@ public class ChannelBase {
     public final RestAnnotations annotations;
 
 
+    private final MessageEditsMixin messageEditsMixin;
+
+
     /**
      * Publish a message on this channel using the REST API.
      * Since the REST API is stateless, this request is made independently
      * of any other request on this or any other channel.
      * @param name the event name
-     * @param data the message payload; see {@link io.ably.types.Data} for
-     * details of supported data types.
+     * @param data the message payload;
      * @throws AblyException
      */
     public void publish(String name, Object data) throws AblyException {
@@ -68,7 +74,7 @@ void publish(Http http, String name, Object data) throws AblyException {
      * of any other request on this or any other channel.
      *
      * @param name the event name
-     * @param data the message payload; see {@link io.ably.types.Data} for
+     * @param data the message payload;
      * @param listener a listener to be notified of the outcome of this message.
      * <p>
      * This listener is invoked on a background thread.
@@ -311,6 +317,117 @@ private BasePaginatedQuery.ResultRequest<PresenceMessage> historyImpl(Http http,
 
     }
 
+    /**
+     * Retrieves the latest version of a specific message by its serial identifier.
+     * <p>
+     * This method allows you to fetch the current state of a message, including any updates
+     * or deletions that have been applied since its creation.
+     *
+     * @param serial The unique serial identifier of the message to retrieve.
+     * @return A {@link Message} object representing the latest version of the message.
+     * @throws AblyException If the message cannot be retrieved or does not exist.
+     */
+    public Message getMessage(String serial) throws AblyException {
+        return messageEditsMixin.getMessage(ably.http, serial);
+    }
+
+    /**
+     * Asynchronously retrieves the latest version of a specific message by its serial identifier.
+     *
+     * @param serial The unique serial identifier of the message to retrieve.
+     * @param callback A callback to handle the result asynchronously.
+     * <p>
+     * This callback is invoked on a background thread.
+     */
+    public void getMessageAsync(String serial, Callback<Message> callback) {
+        messageEditsMixin.getMessageAsync(ably.http, serial, callback);
+    }
+
+    /**
+     * Updates an existing message by its serial identifier using patch semantics.
+     * <p>
+     * Non-null fields in the provided message (name, data, extras) will replace the corresponding
+     * fields in the existing message, while null fields will be left unchanged.
+     *
+     * @param serial The unique serial identifier of the message to update.
+     * @param message A {@link Message} object containing the fields to update.
+     *                Only non-null fields will be applied to the existing message.
+     * @throws AblyException If the update operation fails.
+     */
+    public void updateMessage(String serial, Message message) throws AblyException {
+        messageEditsMixin.updateMessage(ably.http, serial, message);
+    }
+
+    /**
+     * Asynchronously updates an existing message by its serial identifier.
+     *
+     * @param serial The unique serial identifier of the message to update.
+     * @param message A {@link Message} object containing the fields to update.
+     * @param listener A listener to be notified of the outcome of this operation.
+     * <p>
+     * This listener is invoked on a background thread.
+     */
+    public void updateMessageAsync(String serial, Message message, CompletionListener listener) {
+        messageEditsMixin.updateMessageAsync(ably.http, serial, message, listener);
+    }
+
+    /**
+     * Marks a message as deleted by its serial identifier.
+     * <p>
+     * This operation does not remove the message from history; it marks it as deleted
+     * while preserving the full message history. The deleted message can still be
+     * retrieved and will have its action set to MESSAGE_DELETE.
+     *
+     * @param serial The unique serial identifier of the message to delete.
+     * @param message A {@link Message} object that may contain operation metadata such as
+     *                clientId, description, or metadata in the version field.
+     * @throws AblyException If the delete operation fails.
+     */
+    public void deleteMessage(String serial, Message message) throws AblyException {
+        messageEditsMixin.deleteMessage(ably.http, serial, message);
+    }
+
+    /**
+     * Asynchronously marks a message as deleted by its serial identifier.
+     *
+     * @param serial The unique serial identifier of the message to delete.
+     * @param message A {@link Message} object for operation metadata.
+     * @param listener A listener to be notified of the outcome of this operation.
+     * <p>
+     * This listener is invoked on a background thread.
+     */
+    public void deleteMessageAsync(String serial, Message message, CompletionListener listener) {
+        messageEditsMixin.deleteMessageAsync(ably.http, serial, message, listener);
+    }
+
+    /**
+     * Retrieves all historical versions of a specific message.
+     * <p>
+     * This method returns a paginated result containing all versions of the message,
+     * ordered chronologically. Each version includes metadata about when and by whom
+     * the message was modified.
+     *
+     * @param serial The unique serial identifier of the message.
+     * @param params Query parameters for filtering or pagination (e.g., limit, start, end).
+     * @return A {@link PaginatedResult} containing an array of {@link Message} objects
+     *         representing all versions of the message.
+     * @throws AblyException If the versions cannot be retrieved.
+     */
+    public PaginatedResult<Message> getMessageVersions(String serial, Param[] params) throws AblyException {
+        return messageEditsMixin.getMessageVersions(ably.http, serial, params);
+    }
+
+    /**
+     * Asynchronously retrieves all historical versions of a specific message.
+     *
+     * @param serial The unique serial identifier of the message.
+     * @param params Query parameters for filtering or pagination.
+     * @param callback A callback to handle the result asynchronously.
+     */
+    public void getMessageVersionsAsync(String serial, Param[] params, Callback<AsyncPaginatedResult<Message>> callback) throws AblyException {
+        messageEditsMixin.getMessageVersionsAsync(ably.http, serial, params, callback);
+    }
+
     /******************
      * internal
      * @throws AblyException
@@ -323,6 +440,7 @@ private BasePaginatedQuery.ResultRequest<PresenceMessage> historyImpl(Http http,
         this.basePath = "/channels/" + HttpUtils.encodeURIComponent(name);
         this.presence = new Presence();
         this.annotations = new RestAnnotations(name, ably.http, ably.options, options);
+        this.messageEditsMixin = new MessageEditsMixin(basePath, ably.options, options, ably.auth);
     }
 
     private final AblyBase ably;