Add spec annotations applying incoming OBJECT messages for Objects

VeskeR · VeskeR · commit 8976db37d9b7 · 2025-07-08T10:23:24.000+01:00
Spec IDs from [1]. This also fixes a couple of minor spec implementation details. [1] ably/specification#343
diff --git a/src/plugins/objects/livecounter.ts b/src/plugins/objects/livecounter.ts
@@ -168,6 +168,7 @@ export class LiveCounter extends LiveObject<LiveCounterData, LiveCounterUpdate>
 
   /**
    * @internal
+   * @spec RTLC7, RTLC7a
    */
   applyOperation(op: ObjectOperation<ObjectData>, msg: ObjectMessage): void {
     if (op.objectId !== this.getObjectId()) {
@@ -181,6 +182,7 @@ export class LiveCounter extends LiveObject<LiveCounterData, LiveCounterUpdate>
     const opSerial = msg.serial!;
     const opSiteCode = msg.siteCode!;
     if (!this._canApplyOperation(opSerial, opSiteCode)) {
+      // RTLC7b
       this._client.Logger.logAction(
         this._client.logger,
         this._client.Logger.LOG_MICRO,
@@ -191,17 +193,18 @@ export class LiveCounter extends LiveObject<LiveCounterData, LiveCounterUpdate>
     }
     // should update stored site serial immediately. doesn't matter if we successfully apply the op,
     // as it's important to mark that the op was processed by the object
-    this._siteTimeserials[opSiteCode] = opSerial;
+    this._siteTimeserials[opSiteCode] = opSerial; // RTLC7c
 
     if (this.isTombstoned()) {
       // this object is tombstoned so the operation cannot be applied
       return;
     }
 
     let update: LiveCounterUpdate | LiveObjectUpdateNoop;
+    // RTLC7d
     switch (op.action) {
       case ObjectOperationAction.COUNTER_CREATE:
-        update = this._applyCounterCreate(op);
+        update = this._applyCounterCreate(op); // RTLC7d1
         break;
 
       case ObjectOperationAction.COUNTER_INC:
@@ -210,7 +213,7 @@ export class LiveCounter extends LiveObject<LiveCounterData, LiveCounterUpdate>
           // leave an explicit return here, so that TS knows that update object is always set after the switch statement.
           return;
         } else {
-          update = this._applyCounterInc(op.counterOp);
+          update = this._applyCounterInc(op.counterOp); // RTLC7d2
         }
         break;
 
@@ -219,6 +222,7 @@ export class LiveCounter extends LiveObject<LiveCounterData, LiveCounterUpdate>
         break;
 
       default:
+        // RTLC7d3
         throw new this._client.ErrorInfo(
           `Invalid ${op.action} op for LiveCounter objectId=${this.getObjectId()}`,
           92000,
@@ -283,9 +287,8 @@ export class LiveCounter extends LiveObject<LiveCounterData, LiveCounterUpdate>
       // override data for this object with data from the object state
       this._createOperationIsMerged = false; // RTLC6b
       this._dataRef = { data: objectState.counter?.count ?? 0 }; // RTLC6c
-      // RTLC6d
       if (!this._client.Utils.isNil(objectState.createOp)) {
-        this._mergeInitialDataFromCreateOperation(objectState.createOp);
+        this._mergeInitialDataFromCreateOperation(objectState.createOp); // RTLC6d
       }
     }
 
@@ -312,13 +315,14 @@ export class LiveCounter extends LiveObject<LiveCounterData, LiveCounterUpdate>
     return { update: { amount: counterDiff } };
   }
 
+  /** @spec RTLC10 */
   protected _mergeInitialDataFromCreateOperation(objectOperation: ObjectOperation<ObjectData>): LiveCounterUpdate {
     // if a counter object is missing for the COUNTER_CREATE op, the initial value is implicitly 0 in this case.
     // note that it is intentional to SUM the incoming count from the create op.
     // if we got here, it means that current counter instance is missing the initial value in its data reference,
     // which we're going to add now.
-    this._dataRef.data += objectOperation.counter?.count ?? 0; // RTLC6d1
-    this._createOperationIsMerged = true; // RTLC6d2
+    this._dataRef.data += objectOperation.counter?.count ?? 0; // RTLC10a
+    this._createOperationIsMerged = true; // RTLC10b
 
     return { update: { amount: objectOperation.counter?.count ?? 0 } };
   }
@@ -331,8 +335,10 @@ export class LiveCounter extends LiveObject<LiveCounterData, LiveCounterUpdate>
     );
   }
 
+  /** @spec RTLC8 */
   private _applyCounterCreate(op: ObjectOperation<ObjectData>): LiveCounterUpdate | LiveObjectUpdateNoop {
     if (this._createOperationIsMerged) {
+      // RTLC8b
       // There can't be two different create operation for the same object id, because the object id
       // fully encodes that operation. This means we can safely ignore any new incoming create operations
       // if we already merged it once.
@@ -345,11 +351,12 @@ export class LiveCounter extends LiveObject<LiveCounterData, LiveCounterUpdate>
       return { noop: true };
     }
 
-    return this._mergeInitialDataFromCreateOperation(op);
+    return this._mergeInitialDataFromCreateOperation(op); // RTLC8c
   }
 
+  /** @spec RTLC9 */
   private _applyCounterInc(op: ObjectsCounterOp): LiveCounterUpdate {
-    this._dataRef.data += op.amount;
+    this._dataRef.data += op.amount; // RTLC9b
     return { update: { amount: op.amount } };
   }
 }
diff --git a/src/plugins/objects/livemap.ts b/src/plugins/objects/livemap.ts
@@ -374,6 +374,7 @@ export class LiveMap<T extends API.LiveMapType> extends LiveObject<LiveMapData,
 
   /**
    * @internal
+   * @spec RTLM15, RTLM15a
    */
   applyOperation(op: ObjectOperation<ObjectData>, msg: ObjectMessage): void {
     if (op.objectId !== this.getObjectId()) {
@@ -387,6 +388,7 @@ export class LiveMap<T extends API.LiveMapType> extends LiveObject<LiveMapData,
     const opSerial = msg.serial!;
     const opSiteCode = msg.siteCode!;
     if (!this._canApplyOperation(opSerial, opSiteCode)) {
+      // RTLM15b
       this._client.Logger.logAction(
         this._client.logger,
         this._client.Logger.LOG_MICRO,
@@ -397,17 +399,18 @@ export class LiveMap<T extends API.LiveMapType> extends LiveObject<LiveMapData,
     }
     // should update stored site serial immediately. doesn't matter if we successfully apply the op,
     // as it's important to mark that the op was processed by the object
-    this._siteTimeserials[opSiteCode] = opSerial;
+    this._siteTimeserials[opSiteCode] = opSerial; // RTLM15c
 
     if (this.isTombstoned()) {
       // this object is tombstoned so the operation cannot be applied
       return;
     }
 
     let update: LiveMapUpdate<T> | LiveObjectUpdateNoop;
+    // RTLM15d
     switch (op.action) {
       case ObjectOperationAction.MAP_CREATE:
-        update = this._applyMapCreate(op);
+        update = this._applyMapCreate(op); // RTLM15d1
         break;
 
       case ObjectOperationAction.MAP_SET:
@@ -416,7 +419,7 @@ export class LiveMap<T extends API.LiveMapType> extends LiveObject<LiveMapData,
           // leave an explicit return here, so that TS knows that update object is always set after the switch statement.
           return;
         } else {
-          update = this._applyMapSet(op.mapOp, opSerial);
+          update = this._applyMapSet(op.mapOp, opSerial); // RTLM15d2
         }
         break;
 
@@ -426,7 +429,7 @@ export class LiveMap<T extends API.LiveMapType> extends LiveObject<LiveMapData,
           // leave an explicit return here, so that TS knows that update object is always set after the switch statement.
           return;
         } else {
-          update = this._applyMapRemove(op.mapOp, opSerial, msg.serialTimestamp);
+          update = this._applyMapRemove(op.mapOp, opSerial, msg.serialTimestamp); // RTLM15d3
         }
         break;
 
@@ -435,6 +438,7 @@ export class LiveMap<T extends API.LiveMapType> extends LiveObject<LiveMapData,
         break;
 
       default:
+        // RTLM15d4
         throw new this._client.ErrorInfo(
           `Invalid ${op.action} op for LiveMap objectId=${this.getObjectId()}`,
           92000,
@@ -515,9 +519,8 @@ export class LiveMap<T extends API.LiveMapType> extends LiveObject<LiveMapData,
       // override data for this object with data from the object state
       this._createOperationIsMerged = false; // RTLM6b
       this._dataRef = this._liveMapDataFromMapEntries(objectState.map?.entries ?? {}); // RTLM6c
-      // RTLM6d
       if (!this._client.Utils.isNil(objectState.createOp)) {
-        this._mergeInitialDataFromCreateOperation(objectState.createOp);
+        this._mergeInitialDataFromCreateOperation(objectState.createOp); // RTLM6d
       }
     }
 
@@ -603,6 +606,7 @@ export class LiveMap<T extends API.LiveMapType> extends LiveObject<LiveMapData,
     return update;
   }
 
+  /** @spec RTLM17 */
   protected _mergeInitialDataFromCreateOperation(objectOperation: ObjectOperation<ObjectData>): LiveMapUpdate<T> {
     if (this._client.Utils.isNil(objectOperation.map)) {
       // if a map object is missing for the MAP_CREATE op, the initial value is implicitly an empty map.
@@ -611,18 +615,18 @@ export class LiveMap<T extends API.LiveMapType> extends LiveObject<LiveMapData,
     }
 
     const aggregatedUpdate: LiveMapUpdate<T> = { update: {} };
-    // RTLM6d1
+    // RTLM17a
     // in order to apply MAP_CREATE op for an existing map, we should merge their underlying entries keys.
     // we can do this by iterating over entries from MAP_CREATE op and apply changes on per-key basis as if we had MAP_SET, MAP_REMOVE operations.
     Object.entries(objectOperation.map.entries ?? {}).forEach(([key, entry]) => {
       // for a MAP_CREATE operation we must use the serial value available on an entry, instead of a serial on a message
       const opSerial = entry.timeserial;
       let update: LiveMapUpdate<T> | LiveObjectUpdateNoop;
       if (entry.tombstone === true) {
-        // RTLM6d1b - entry in MAP_CREATE op is removed, try to apply MAP_REMOVE op
+        // RTLM17a2 - entry in MAP_CREATE op is removed, try to apply MAP_REMOVE op
         update = this._applyMapRemove({ key }, opSerial, entry.serialTimestamp);
       } else {
-        // RTLM6d1a - entry in MAP_CREATE op is not removed, try to set it via MAP_SET op
+        // RTLM17a1 - entry in MAP_CREATE op is not removed, try to set it via MAP_SET op
         update = this._applyMapSet({ key, data: entry.data }, opSerial);
       }
 
@@ -635,7 +639,7 @@ export class LiveMap<T extends API.LiveMapType> extends LiveObject<LiveMapData,
       Object.assign(aggregatedUpdate.update, update.update);
     });
 
-    this._createOperationIsMerged = true; // RTLM6d2
+    this._createOperationIsMerged = true; // RTLM17b
 
     return aggregatedUpdate;
   }
@@ -648,8 +652,10 @@ export class LiveMap<T extends API.LiveMapType> extends LiveObject<LiveMapData,
     );
   }
 
+  /** @spec RTLM16 */
   private _applyMapCreate(op: ObjectOperation<ObjectData>): LiveMapUpdate<T> | LiveObjectUpdateNoop {
     if (this._createOperationIsMerged) {
+      // RTLM16b
       // There can't be two different create operation for the same object id, because the object id
       // fully encodes that operation. This means we can safely ignore any new incoming create operations
       // if we already merged it once.
@@ -663,20 +669,21 @@ export class LiveMap<T extends API.LiveMapType> extends LiveObject<LiveMapData,
     }
 
     if (this._semantics !== op.map?.semantics) {
+      // RTLM16c
       throw new this._client.ErrorInfo(
         `Cannot apply MAP_CREATE op on LiveMap objectId=${this.getObjectId()}; map's semantics=${this._semantics}, but op expected ${op.map?.semantics}`,
         92000,
         500,
       );
     }
 
-    return this._mergeInitialDataFromCreateOperation(op);
+    return this._mergeInitialDataFromCreateOperation(op); // RTLM16d
   }
 
   /** @spec RTLM7 */
   private _applyMapSet(
-    op: ObjectsMapOp<ObjectData>,
-    opSerial: string | undefined,
+    op: ObjectsMapOp<ObjectData>, // RTLM7d1
+    opSerial: string | undefined, // RTLM7d2
   ): LiveMapUpdate<T> | LiveObjectUpdateNoop {
     const { ErrorInfo, Utils } = this._client;
 
@@ -740,8 +747,8 @@ export class LiveMap<T extends API.LiveMapType> extends LiveObject<LiveMapData,
 
   /** @spec RTLM8 */
   private _applyMapRemove(
-    op: ObjectsMapOp<ObjectData>,
-    opSerial: string | undefined,
+    op: ObjectsMapOp<ObjectData>, // RTLM8c1
+    opSerial: string | undefined, // RTLM8c2
     opTimestamp: number | undefined,
   ): LiveMapUpdate<T> | LiveObjectUpdateNoop {
     const existingEntry = this._dataRef.data.get(op.key);
@@ -881,17 +888,21 @@ export class LiveMap<T extends API.LiveMapType> extends LiveObject<LiveMapData,
 
     // RTLM5d2f - otherwise, it has an objectId reference, and we should get the actual object from the pool
     const objectId = (data as ObjectIdObjectData).objectId;
-    const refObject: LiveObject | undefined = this._objects.getPool().get(objectId);
-    if (!refObject) {
-      return undefined; // RTLM5d2f1
-    }
+    if (objectId != null) {
+      const refObject: LiveObject | undefined = this._objects.getPool().get(objectId);
+      if (!refObject) {
+        return undefined; // RTLM5d2f1
+      }
+
+      if (refObject.isTombstoned()) {
+        // tombstoned objects must not be surfaced to the end users
+        return undefined;
+      }
 
-    if (refObject.isTombstoned()) {
-      // tombstoned objects must not be surfaced to the end users
-      return undefined;
+      return refObject; // RTLM5d2f2
     }
 
-    return refObject; // RTLM5d2f2
+    return undefined; // RTLM5d2g
   }
 
   /** @spec RTLM14 */
diff --git a/src/plugins/objects/liveobject.ts b/src/plugins/objects/liveobject.ts
@@ -35,21 +35,22 @@ export interface OnLiveObjectLifecycleEventResponse {
   off(): void;
 }
 
+/** @spec RTLO1, RTLO2 */
 export abstract class LiveObject<
   TData extends LiveObjectData = LiveObjectData,
   TUpdate extends LiveObjectUpdate = LiveObjectUpdate,
 > {
   protected _client: BaseClient;
   protected _subscriptions: EventEmitter;
   protected _lifecycleEvents: EventEmitter;
-  protected _objectId: string;
+  protected _objectId: string; // RTLO3a
   /**
    * Represents an aggregated value for an object, which combines the initial value for an object from the create operation,
    * and all object operations applied to the object.
    */
   protected _dataRef: TData;
-  protected _siteTimeserials: Record<string, string>;
-  protected _createOperationIsMerged: boolean;
+  protected _siteTimeserials: Record<string, string>; // RTLO3b
+  protected _createOperationIsMerged: boolean; // RTLO3c
   private _tombstone: boolean;
   private _tombstonedAt: number | undefined;
 
@@ -60,11 +61,11 @@ export abstract class LiveObject<
     this._client = this._objects.getClient();
     this._subscriptions = new this._client.EventEmitter(this._client.logger);
     this._lifecycleEvents = new this._client.EventEmitter(this._client.logger);
-    this._objectId = objectId;
+    this._objectId = objectId; // RTLO3a1
     this._dataRef = this._getZeroValueData();
     // use empty map of serials by default, so any future operation can be applied to this object
-    this._siteTimeserials = {};
-    this._createOperationIsMerged = false;
+    this._siteTimeserials = {}; // RTLO3b1
+    this._createOperationIsMerged = false; // RTLO3c1
     this._tombstone = false;
   }
 
@@ -198,18 +199,20 @@ export abstract class LiveObject<
    *
    * An operation should be applied if its serial is strictly greater than the serial in the `siteTimeserials` map for the same site.
    * If `siteTimeserials` map does not contain a serial for the same site, the operation should be applied.
+   *
+   * @spec RTLO4a
    */
   protected _canApplyOperation(opSerial: string | undefined, opSiteCode: string | undefined): boolean {
     if (!opSerial) {
-      throw new this._client.ErrorInfo(`Invalid serial: ${opSerial}`, 92000, 500);
+      throw new this._client.ErrorInfo(`Invalid serial: ${opSerial}`, 92000, 500); // RTLO4a3
     }
 
     if (!opSiteCode) {
-      throw new this._client.ErrorInfo(`Invalid site code: ${opSiteCode}`, 92000, 500);
+      throw new this._client.ErrorInfo(`Invalid site code: ${opSiteCode}`, 92000, 500); // RTLO4a3
     }
 
-    const siteSerial = this._siteTimeserials[opSiteCode];
-    return !siteSerial || opSerial > siteSerial;
+    const siteSerial = this._siteTimeserials[opSiteCode]; // RTLO4a4
+    return !siteSerial || opSerial > siteSerial; // RTLO4a5, RTLO4a6
   }
 
   protected _applyObjectDelete(objectMessage: ObjectMessage): TUpdate {
diff --git a/src/plugins/objects/objects.ts b/src/plugins/objects/objects.ts
