Support MAP_CLEAR object operation

See DR [1], realtime implementation [2] and spec [3]

Resolves AIT-458

[1] https://ably.atlassian.net/wiki/x/DABECAE
[2] ably/realtime#8074
[3] ably/specification#432

Author: VeskeR

liveobjects.d.ts

@@ -1489,6 +1489,10 @@ declare namespace ObjectOperationActions {
    * Object operation action for deleting an object.
    */
   type OBJECT_DELETE = 'object.delete';
+  /**
+   * Object operation action for clearing a map object.
+   */
+  type MAP_CLEAR = 'map.clear';
 }
 
 /**
@@ -1500,7 +1504,8 @@ export type ObjectOperationAction =
   | ObjectOperationActions.MAP_REMOVE
   | ObjectOperationActions.COUNTER_CREATE
   | ObjectOperationActions.COUNTER_INC
-  | ObjectOperationActions.OBJECT_DELETE;
+  | ObjectOperationActions.OBJECT_DELETE
+  | ObjectOperationActions.MAP_CLEAR;
 
 /**
  * The namespace containing the different types of map object semantics.
@@ -1607,6 +1612,10 @@ export interface ObjectOperation {
    * The payload for the operation if the action is {@link ObjectOperationActions.OBJECT_DELETE}.
    */
   objectDelete?: ObjectDelete;
+  /**
+   * The payload for the operation if the action is {@link ObjectOperationActions.MAP_CLEAR}.
+   */
+  mapClear?: MapClear;
 
   /**
    * The payload for the operation if it is a mutation operation on a map object.
@@ -1735,6 +1744,11 @@ export interface CounterInc {
  */
 export interface ObjectDelete {}
 
+/**
+ * Describes the payload for a MAP_CLEAR operation.
+ */
+export interface MapClear {}
+
 /**
  * Represents a value in an object on a channel.
  */

src/plugins/liveobjects/livemap.ts

@@ -56,6 +56,7 @@ export class LiveMap<T extends Record<string, Value> = Record<string, Value>>
   implements PublicLiveMap<T>
 {
   declare readonly [__livetype]: 'LiveMap'; // type-only, unique symbol to satisfy branded interfaces, no JS emitted
+  private _clearTimeserial?: string;
 
   constructor(
     realtimeObject: RealtimeObject,
@@ -358,6 +359,10 @@ export class LiveMap<T extends Record<string, Value> = Record<string, Value>>
         update = this._applyObjectDelete(msg);
         break;
 
+      case ObjectOperationAction.MAP_CLEAR:
+        update = this._applyMapClear(msg);
+        break;
+
       default:
         throw new this._client.ErrorInfo(
           `Invalid ${op.action} op for LiveMap objectId=${this.getObjectId()}`,
@@ -440,6 +445,7 @@ export class LiveMap<T extends Record<string, Value> = Record<string, Value>>
     } else {
       // otherwise override data for this object with data from the object state
       this._createOperationIsMerged = false; // RTLM6b
+      this._clearTimeserial = objectState.map?.clearTimeserial;
       this._dataRef = this._liveMapDataFromMapEntries(objectState.map?.entries ?? {}); // RTLM6c
       // RTLM6d
       if (!this._client.Utils.isNil(objectState.createOp)) {
@@ -737,9 +743,20 @@ export class LiveMap<T extends Record<string, Value> = Record<string, Value>>
   ): LiveMapUpdate<T> | LiveObjectUpdateNoop {
     const { ErrorInfo, Utils } = this._client;
 
+    // Check operation's serial against clearTimeserial first
+    if (this._clearTimeserial && (!opSerial || this._clearTimeserial >= opSerial)) {
+      this._client.Logger.logAction(
+        this._client.logger,
+        this._client.Logger.LOG_MICRO,
+        'LiveMap._applyMapSet()',
+        `skipping update for key="${op.key}": op serial ${opSerial} < clear serial ${this._clearTimeserial}; objectId=${this.getObjectId()}`,
+      );
+      return { noop: true };
+    }
+
     const existingEntry = this._dataRef.data.get(op.key);
     // RTLM7a
-    if (existingEntry && !this._canApplyMapOperation(existingEntry.timeserial, opSerial)) {
+    if (existingEntry && !this._canApplyMapEntryOperation(existingEntry.timeserial, opSerial)) {
       // RTLM7a1 - the operation's serial <= the entry's serial, ignore the operation.
       this._client.Logger.logAction(
         this._client.logger,
@@ -823,9 +840,11 @@ export class LiveMap<T extends Record<string, Value> = Record<string, Value>>
     opTimestamp: number | undefined,
     msg: ObjectMessage,
   ): LiveMapUpdate<T> | LiveObjectUpdateNoop {
+    // No need to check against clearTimeserial - a remove after a clear is valid
+
     const existingEntry = this._dataRef.data.get(op.key);
     // RTLM8a
-    if (existingEntry && !this._canApplyMapOperation(existingEntry.timeserial, opSerial)) {
+    if (existingEntry && !this._canApplyMapEntryOperation(existingEntry.timeserial, opSerial)) {
       // RTLM8a1 - the operation's serial <= the entry's serial, ignore the operation.
       this._client.Logger.logAction(
         this._client.logger,
@@ -886,12 +905,91 @@ export class LiveMap<T extends Record<string, Value> = Record<string, Value>>
     return update;
   }
 
+  private _applyMapClear(objectMessage: ObjectMessage): LiveMapUpdate<T> | LiveObjectUpdateNoop {
+    const opSerial = objectMessage.serial!;
+
+    if (this._clearTimeserial == null || opSerial > this._clearTimeserial) {
+      this._client.Logger.logAction(
+        this._client.logger,
+        this._client.Logger.LOG_MICRO,
+        'LiveMap._applyMapClear()',
+        `updating clearTimeserial; previous=${this._clearTimeserial}, new=${opSerial}; objectId=${this.getObjectId()}`,
+      );
+      this._clearTimeserial = opSerial;
+    } else {
+      this._client.Logger.logAction(
+        this._client.logger,
+        this._client.Logger.LOG_MICRO,
+        'LiveMap._applyMapClear()',
+        `skipping MAP_CLEAR: op serial ${opSerial} <= current clear serial ${this._clearTimeserial}; objectId=${this.getObjectId()}`,
+      );
+      return { noop: true };
+    }
+
+    let tombstonedAt: number;
+    if (objectMessage.serialTimestamp != null) {
+      tombstonedAt = objectMessage.serialTimestamp;
+    } else {
+      this._client.Logger.logAction(
+        this._client.logger,
+        this._client.Logger.LOG_MINOR,
+        'LiveMap._applyMapClear()',
+        `map has been cleared but no "serialTimestamp" found in the message, using local clock instead; objectId=${this.getObjectId()}`,
+      );
+      tombstonedAt = Date.now(); // best-effort estimate since no timestamp provided by the server
+    }
+
+    const update: LiveMapUpdate<T> = {
+      update: {},
+      objectMessage,
+      _type: 'LiveMapUpdate',
+    };
+
+    for (const [key, entry] of this._dataRef.data.entries()) {
+      const entrySerial = entry.timeserial;
+      if (entrySerial == null || this._clearTimeserial >= entrySerial) {
+        this._client.Logger.logAction(
+          this._client.logger,
+          this._client.Logger.LOG_MICRO,
+          'LiveMap._applyMapClear()',
+          `clearing entry; key="${key}", entry serial=${entrySerial}, clear serial=${this._clearTimeserial}, objectId=${this.getObjectId()}`,
+        );
+
+        // Handle parent reference removal for object references
+        if (entry.data && 'objectId' in entry.data) {
+          // Remove parent reference from the object that was being referenced
+          const referencedObject = this._realtimeObject.getPool().get(entry.data.objectId);
+          if (referencedObject) {
+            referencedObject.removeParentReference(this, key);
+          }
+        }
+
+        entry.tombstone = true;
+        entry.tombstonedAt = tombstonedAt;
+        entry.timeserial = this._clearTimeserial;
+        entry.data = undefined;
+
+        const typedKey: keyof T & string = key;
+        update.update[typedKey] = 'removed';
+      } else {
+        this._client.Logger.logAction(
+          this._client.logger,
+          this._client.Logger.LOG_MICRO,
+          'LiveMap._applyMapClear()',
+          `skipping clearing entry; key="${key}", entry serial=${entrySerial}, clear serial=${this._clearTimeserial}, objectId=${this.getObjectId()}`,
+        );
+      }
+    }
+
+    return update;
+  }
+
   /**
    * Returns true if the serials of the given operation and entry indicate that
    * the operation should be applied to the entry, following the CRDT semantics of this LiveMap.
    * @spec RTLM9
    */
-  private _canApplyMapOperation(mapEntrySerial: string | undefined, opSerial: string | undefined): boolean {
+  private _canApplyMapEntryOperation(mapEntrySerial: string | undefined, opSerial: string | undefined): boolean {
     // for LWW CRDT semantics (the only supported LiveMap semantic) an operation
     // should only be applied if its serial is strictly greater ("after") than an entry's serial.
 

src/plugins/liveobjects/objectmessage.ts

@@ -11,6 +11,7 @@ const operationActions: ObjectsApi.ObjectOperationAction[] = [
   'counter.create',
   'counter.inc',
   'object.delete',
+  'map.clear',
 ];
 
 const mapSemantics: ObjectsApi.ObjectsMapSemantics[] = ['lww'];
@@ -25,6 +26,7 @@ export enum ObjectOperationAction {
   COUNTER_CREATE = 3,
   COUNTER_INC = 4,
   OBJECT_DELETE = 5,
+  MAP_CLEAR = 6,
 }
 
 /** @spec OMP2 */
@@ -119,6 +121,8 @@ export interface ObjectsMap<TData> {
   semantics?: ObjectsMapSemantics; // OMP3a
   /** The map entries, indexed by key. */
   entries?: Record<string, ObjectsMapEntry<TData>>; // OMP3b
+  /** The {@link ObjectMessage.serial} value of the last `MAP_CLEAR` operation applied to the map. If no `MAP_CLEAR` has been applied, this field is omitted */
+  clearTimeserial?: string; // OMP3c
 }
 
 /**
@@ -227,6 +231,13 @@ export interface CounterCreateWithObjectId {
   _derivedFrom?: CounterCreate;
 }
 
+/**
+ * A MapClear describes the payload for a MAP_CLEAR operation
+ */
+export interface MapClear {
+  // Empty message, MAP_CLEAR requires no operation-specific data
+}
+
 /**
  * An ObjectOperation describes an operation to be applied to an object on a channel.
  * @spec OOP1
@@ -273,6 +284,10 @@ export interface ObjectOperation<TData> {
    * Contains the nonce and JSON-encoded initial value from {@link CounterCreate} for object ID verification.
    */
   counterCreateWithObjectId?: CounterCreateWithObjectId; // OOP3q
+  /**
+   * The payload for MAP_CLEAR operation.
+   */
+  mapClear?: MapClear;
 }
 
 /**
@@ -487,7 +502,7 @@ function toUserFacingMapEntry(entry: ObjectsMapEntry<ObjectData>): ObjectsApi.Ob
 }
 
 function toUserFacingObjectOperation(operation: ObjectOperation<ObjectData>): ObjectsApi.ObjectOperation {
-  const { mapSet: internalMapSet, mapRemove, counterInc, objectDelete } = operation;
+  const { mapSet: internalMapSet, mapRemove, counterInc, objectDelete, mapClear } = operation;
 
   // resolve *Create from direct property or from *CreateWithObjectId._derivedFrom
   const internalMapCreate = operation.mapCreate ?? operation.mapCreateWithObjectId?._derivedFrom;
@@ -537,6 +552,7 @@ function toUserFacingObjectOperation(operation: ObjectOperation<ObjectData>): Ob
     counterCreate,
     counterInc,
     objectDelete,
+    mapClear,
     // deprecated fields
     mapOp,
     counterOp,

src/plugins/liveobjects/realtimeobject.ts

@@ -522,7 +522,8 @@ export class RealtimeObject {
         case ObjectOperationAction.MAP_SET:
         case ObjectOperationAction.MAP_REMOVE:
         case ObjectOperationAction.COUNTER_INC:
-        case ObjectOperationAction.OBJECT_DELETE: {
+        case ObjectOperationAction.OBJECT_DELETE:
+        case ObjectOperationAction.MAP_CLEAR: {
           // we can receive an op for an object id we don't have yet in the pool. instead of buffering such operations,
           // we can create a zero-value object for the provided object id and apply the operation to that zero-value object.
           // this also means that all objects are capable of applying the corresponding *_CREATE ops on themselves,

test/common/modules/liveobjects_helper.js

@@ -13,6 +13,7 @@ define(['ably', 'shared_helper', 'liveobjects'], function (Ably, Helper, LiveObj
     COUNTER_CREATE: 3,
     COUNTER_INC: 4,
     OBJECT_DELETE: 5,
+    MAP_CLEAR: 6,
   };
   const ACTION_STRINGS = {
     MAP_CREATE: 'MAP_CREATE',
@@ -21,6 +22,7 @@ define(['ably', 'shared_helper', 'liveobjects'], function (Ably, Helper, LiveObj
     COUNTER_CREATE: 'COUNTER_CREATE',
     COUNTER_INC: 'COUNTER_INC',
     OBJECT_DELETE: 'OBJECT_DELETE',
+    MAP_CLEAR: 'MAP_CLEAR',
   };
 
   class LiveObjectsHelper {
@@ -187,8 +189,21 @@ define(['ably', 'shared_helper', 'liveobjects'], function (Ably, Helper, LiveObj
       return op;
     }
 
+    mapClearOp(opts) {
+      const { objectId } = opts ?? {};
+      const op = {
+        operation: {
+          action: ACTIONS.MAP_CLEAR,
+          objectId,
+          mapClear: {},
+        },
+      };
+
+      return op;
+    }
+
     mapObject(opts) {
-      const { objectId, siteTimeserials, initialEntries, materialisedEntries, tombstone } = opts;
+      const { objectId, siteTimeserials, initialEntries, materialisedEntries, tombstone, clearTimeserial } = opts;
       const obj = {
         object: {
           objectId,
@@ -197,6 +212,7 @@ define(['ably', 'shared_helper', 'liveobjects'], function (Ably, Helper, LiveObj
           map: {
             semantics: 0,
             entries: materialisedEntries,
+            ...(clearTimeserial != null ? { clearTimeserial } : {}),
           },
         },
       };

test/common/modules/private_api_recorder.js

@@ -42,6 +42,7 @@ define(['test/support/output_directory_paths'], function (outputDirectoryPaths)
     'call.channel.processMessage',
     'call.channel.requestState',
     'call.channel.sendPresence',
+    'call.channel.sendState',
     'call.channel.sync',
     'call.connectionManager.activeProtocol.getTransport',
     'call.connectionManager.clearConnection',
@@ -84,6 +85,7 @@ define(['test/support/output_directory_paths'], function (outputDirectoryPaths)
     'read.Defaults.version',
     'read.EventEmitter.events',
     'read.LiveMap._dataRef.data',
+    'read.LiveObject._parentReferences',
     'read.LiveObject._subscriptions',
     'read.PathObjectSubscriptionRegister._subscriptions',
     'read.Platform.Config.push',