Add spec annotations for tombstones and OBJECT_DELETE op for Objects

VeskeR · VeskeR · commit 1cb2b25bbbe8 · 2025-07-22T17:53:13.000+01:00
Spec IDs from [1]. [1] ably/specification#350
diff --git a/src/plugins/objects/defaults.ts b/src/plugins/objects/defaults.ts
@@ -1,5 +1,5 @@
 export const DEFAULTS = {
-  gcInterval: 1000 * 60 * 5, // 5 minutes
+  gcInterval: 1000 * 60 * 5, // RTO10a, 5 minutes
   /**
    * The SDK will attempt to use the `objectsGCGracePeriod` value provided by the server in the `connectionDetails` object of the `CONNECTED` event.
    * If the server does not provide this value, the SDK will fall back to this default value.
@@ -9,5 +9,5 @@ export const DEFAULTS = {
    *
    * Applies both for map entries tombstones and object tombstones.
    */
-  gcGracePeriod: 1000 * 60 * 60 * 24, // 24 hours
+  gcGracePeriod: 1000 * 60 * 60 * 24, // RTO10b3, 24 hours
 };
diff --git a/src/plugins/objects/livecounter.ts b/src/plugins/objects/livecounter.ts
@@ -196,7 +196,7 @@ export class LiveCounter extends LiveObject<LiveCounterData, LiveCounterUpdate>
     this._siteTimeserials[opSiteCode] = opSerial; // RTLC7c
 
     if (this.isTombstoned()) {
-      // this object is tombstoned so the operation cannot be applied
+      // RTLC7e - this object is tombstoned so the operation cannot be applied
       return;
     }
 
@@ -218,7 +218,7 @@ export class LiveCounter extends LiveObject<LiveCounterData, LiveCounterUpdate>
         break;
 
       case ObjectOperationAction.OBJECT_DELETE:
-        update = this._applyObjectDelete(msg);
+        update = this._applyObjectDelete(msg); // RTLC7d4, RTLC7d4a
         break;
 
       default:
@@ -275,14 +275,14 @@ export class LiveCounter extends LiveObject<LiveCounterData, LiveCounterUpdate>
     this._siteTimeserials = objectState.siteTimeserials ?? {}; // RTLC6a
 
     if (this.isTombstoned()) {
-      // this object is tombstoned. this is a terminal state which can't be overridden. skip the rest of object state message processing
-      return { noop: true };
+      // RTLC6e - this object is tombstoned. this is a terminal state which can't be overridden. skip the rest of object state message processing
+      return { noop: true }; // RTLC6e1
     }
 
     const previousDataRef = this._dataRef;
     if (objectState.tombstone) {
       // tombstone this object and ignore the data from the object state message
-      this.tombstone(objectMessage);
+      this.tombstone(objectMessage); // RTLC6f
     } else {
       // override data for this object with data from the object state
       this._createOperationIsMerged = false; // RTLC6b
@@ -294,7 +294,7 @@ export class LiveCounter extends LiveObject<LiveCounterData, LiveCounterUpdate>
 
     // if object got tombstoned, the update object will include all data that got cleared.
     // otherwise it is a diff between previous value and new value from object state.
-    return this._updateFromDataDiff(previousDataRef, this._dataRef);
+    return this._updateFromDataDiff(previousDataRef, this._dataRef); // RTLC6f1
   }
 
   /**
diff --git a/src/plugins/objects/livemap.ts b/src/plugins/objects/livemap.ts
@@ -40,7 +40,7 @@ export type LiveMapObjectData = ObjectIdObjectData | ValueObjectData;
 
 export interface LiveMapEntry {
   tombstone: boolean;
-  tombstonedAt: number | undefined;
+  tombstonedAt: number | undefined; // RTLM3a1
   timeserial: string | undefined;
   data: LiveMapObjectData | undefined;
 }
@@ -300,6 +300,7 @@ export class LiveMap<T extends API.LiveMapType> extends LiveObject<LiveMapData,
   get<TKey extends keyof T & string>(key: TKey): T[TKey] | undefined {
     this._objects.throwIfInvalidAccessApiConfiguration(); // RTLM5b, RTLM5c
 
+    // RTLM5e
     if (this.isTombstoned()) {
       return undefined as T[TKey];
     }
@@ -429,7 +430,7 @@ export class LiveMap<T extends API.LiveMapType> extends LiveObject<LiveMapData,
     this._siteTimeserials[opSiteCode] = opSerial; // RTLM15c
 
     if (this.isTombstoned()) {
-      // this object is tombstoned so the operation cannot be applied
+      // RTLM15e - this object is tombstoned so the operation cannot be applied
       return;
     }
 
@@ -461,7 +462,7 @@ export class LiveMap<T extends API.LiveMapType> extends LiveObject<LiveMapData,
         break;
 
       case ObjectOperationAction.OBJECT_DELETE:
-        update = this._applyObjectDelete(msg);
+        update = this._applyObjectDelete(msg); // RTLM15d5, RTLM15d5a
         break;
 
       default:
@@ -534,14 +535,14 @@ export class LiveMap<T extends API.LiveMapType> extends LiveObject<LiveMapData,
     this._siteTimeserials = objectState.siteTimeserials ?? {}; // RTLM6a
 
     if (this.isTombstoned()) {
-      // this object is tombstoned. this is a terminal state which can't be overridden. skip the rest of object state message processing
-      return { noop: true };
+      // RTLM6e - this object is tombstoned. this is a terminal state which can't be overridden. skip the rest of object state message processing
+      return { noop: true }; // RTLM6e1
     }
 
     const previousDataRef = this._dataRef;
     if (objectState.tombstone) {
       // tombstone this object and ignore the data from the object state message
-      this.tombstone(objectMessage);
+      this.tombstone(objectMessage); // RTLM6f
     } else {
       // override data for this object with data from the object state
       this._createOperationIsMerged = false; // RTLM6b
@@ -553,19 +554,21 @@ export class LiveMap<T extends API.LiveMapType> extends LiveObject<LiveMapData,
 
     // if object got tombstoned, the update object will include all data that got cleared.
     // otherwise it is a diff between previous value and new value from object state.
-    return this._updateFromDataDiff(previousDataRef, this._dataRef);
+    return this._updateFromDataDiff(previousDataRef, this._dataRef); // RTLM6f1
   }
 
   /**
    * @internal
+   * @spec RTLM19
    */
   onGCInterval(): void {
     // should remove any tombstoned entries from the underlying map data that have exceeded the GC grace period
 
+    // RTLM19a
     const keysToDelete: string[] = [];
     for (const [key, value] of this._dataRef.data.entries()) {
       if (value.tombstone === true && Date.now() - value.tombstonedAt! >= this._objects.gcGracePeriod) {
-        keysToDelete.push(key);
+        keysToDelete.push(key); // RTLM19a1
       }
     }
 
@@ -764,14 +767,14 @@ export class LiveMap<T extends API.LiveMapType> extends LiveObject<LiveMapData,
     if (existingEntry) {
       // RTLM7a2
       existingEntry.tombstone = false; // RTLM7a2c
-      existingEntry.tombstonedAt = undefined;
+      existingEntry.tombstonedAt = undefined; // RTLM7a2d
       existingEntry.timeserial = opSerial; // RTLM7a2b
       existingEntry.data = liveData; // RTLM7a2a
     } else {
       // RTLM7b, RTLM7b1
       const newEntry: LiveMapEntry = {
         tombstone: false, // RTLM7b2
-        tombstonedAt: undefined,
+        tombstonedAt: undefined, // RTLM7b3
         timeserial: opSerial,
         data: liveData,
       };
@@ -789,7 +792,7 @@ export class LiveMap<T extends API.LiveMapType> extends LiveObject<LiveMapData,
   private _applyMapRemove(
     op: ObjectsMapOp<ObjectData>, // RTLM8c1
     opSerial: string | undefined, // RTLM8c2
-    opTimestamp: number | undefined,
+    opTimestamp: number | undefined, // RTLM8c3
   ): LiveMapUpdate<T> | LiveObjectUpdateNoop {
     const existingEntry = this._dataRef.data.get(op.key);
     // RTLM8a
@@ -804,30 +807,33 @@ export class LiveMap<T extends API.LiveMapType> extends LiveObject<LiveMapData,
       return { noop: true };
     }
 
+    // RTLM8f
     let tombstonedAt: number;
     if (opTimestamp != null) {
-      tombstonedAt = opTimestamp;
+      tombstonedAt = opTimestamp; // RTLM8f1
     } else {
+      // RTLM8f2a
       this._client.Logger.logAction(
         this._client.logger,
         this._client.Logger.LOG_MINOR,
         'LiveMap._applyMapRemove()',
         `map key has been removed but no "serialTimestamp" found in the message, using local clock instead; key="${op.key}", objectId=${this.getObjectId()}`,
       );
+      // RTLM8f2
       tombstonedAt = Date.now(); // best-effort estimate since no timestamp provided by the server
     }
 
     if (existingEntry) {
       // RTLM8a2
       existingEntry.tombstone = true; // RTLM8a2c
-      existingEntry.tombstonedAt = tombstonedAt;
+      existingEntry.tombstonedAt = tombstonedAt; // RTLM8a2d
       existingEntry.timeserial = opSerial; // RTLM8a2b
       existingEntry.data = undefined; // RTLM8a2a
     } else {
       // RTLM8b, RTLM8b1
       const newEntry: LiveMapEntry = {
         tombstone: true, // RTLM8b2
-        tombstonedAt: tombstonedAt,
+        tombstonedAt: tombstonedAt, // RTLM8b3
         timeserial: opSerial,
         data: undefined,
       };
@@ -896,14 +902,16 @@ export class LiveMap<T extends API.LiveMapType> extends LiveObject<LiveMapData,
       let tombstonedAt: number | undefined;
       if (entry.tombstone === true) {
         if (entry.serialTimestamp != null) {
-          tombstonedAt = entry.serialTimestamp;
+          tombstonedAt = entry.serialTimestamp; // RTLM6c1a
         } else {
+          // RTLM6c1b1
           this._client.Logger.logAction(
             this._client.logger,
             this._client.Logger.LOG_MINOR,
             'LiveMap._liveMapDataFromMapEntries()',
             `map key is removed but no "serialTimestamp" found, using local clock instead; key="${key}", objectId=${this.getObjectId()}`,
           );
+          // RTLM6c1b
           tombstonedAt = Date.now(); // best-effort estimate since no timestamp provided by the server
         }
       }
@@ -913,7 +921,7 @@ export class LiveMap<T extends API.LiveMapType> extends LiveObject<LiveMapData,
         data: liveData,
         // consider object as tombstoned only if we received an explicit flag stating that. otherwise it exists
         tombstone: entry.tombstone === true,
-        tombstonedAt,
+        tombstonedAt, // RTLM6c1
       };
 
       liveMapData.data.set(key, liveDataEntry);
@@ -950,7 +958,7 @@ export class LiveMap<T extends API.LiveMapType> extends LiveObject<LiveMapData,
       }
 
       if (refObject.isTombstoned()) {
-        // tombstoned objects must not be surfaced to the end users
+        // RTLM5d2f3 - tombstoned objects must not be surfaced to the end users
         return undefined;
       }
 
@@ -973,7 +981,7 @@ export class LiveMap<T extends API.LiveMapType> extends LiveObject<LiveMapData,
 
       if (refObject?.isTombstoned()) {
         // entry that points to tombstoned object should be considered tombstoned as well
-        return true;
+        return true; // RTLM14c
       }
     }
 
diff --git a/src/plugins/objects/liveobject.ts b/src/plugins/objects/liveobject.ts
@@ -51,8 +51,8 @@ export abstract class LiveObject<
   protected _dataRef: TData;
   protected _siteTimeserials: Record<string, string>; // RTLO3b
   protected _createOperationIsMerged: boolean; // RTLO3c
-  private _tombstone: boolean;
-  private _tombstonedAt: number | undefined;
+  private _tombstone: boolean; // RTLO3d
+  private _tombstonedAt: number | undefined; // RTLO3e, RTLO3e1
 
   protected constructor(
     protected _objects: Objects,
@@ -66,7 +66,7 @@ export abstract class LiveObject<
     // use empty map of serials by default, so any future operation can be applied to this object
     this._siteTimeserials = {}; // RTLO3b1
     this._createOperationIsMerged = false; // RTLO3c1
-    this._tombstone = false;
+    this._tombstone = false; // RTLO3d1
   }
 
   subscribe(listener: (update: TUpdate) => void): SubscribeResponse {
@@ -151,21 +151,25 @@ export abstract class LiveObject<
    * Clears the object's data, cancels any buffered operations and sets the tombstone flag to `true`.
    *
    * @internal
+   * @spec RTLO4e
    */
   tombstone(objectMessage: ObjectMessage): TUpdate {
-    this._tombstone = true;
+    this._tombstone = true; // RTLO4e2
+    // RTLO4e3
     if (objectMessage.serialTimestamp != null) {
-      this._tombstonedAt = objectMessage.serialTimestamp;
+      this._tombstonedAt = objectMessage.serialTimestamp; // RTLO4e3a
     } else {
+      // RTLO4e3b1
       this._client.Logger.logAction(
         this._client.logger,
         this._client.Logger.LOG_MINOR,
         'LiveObject.tombstone()',
         `object has been tombstoned but no "serialTimestamp" found in the message, using local clock instead; objectId=${this.getObjectId()}`,
       );
+      // RTLO4e3b
       this._tombstonedAt = Date.now(); // best-effort estimate since no timestamp provided by the server
     }
-    const update = this.clearData();
+    const update = this.clearData(); // RTLO4e4
     this._lifecycleEvents.emit(LiveObjectLifecycleEvent.deleted);
 
     return update;
@@ -215,8 +219,9 @@ export abstract class LiveObject<
     return !siteSerial || opSerial > siteSerial; // RTLO4a5, RTLO4a6
   }
 
+  /** @spec RTLO5 */
   protected _applyObjectDelete(objectMessage: ObjectMessage): TUpdate {
-    return this.tombstone(objectMessage);
+    return this.tombstone(objectMessage); // RTLO5b
   }
 
   /**
diff --git a/src/plugins/objects/objects.ts b/src/plugins/objects/objects.ts
@@ -67,9 +67,9 @@ export class Objects {
     this._bufferedObjectOperations = []; // RTO7a1
     // use server-provided objectsGCGracePeriod if available, and subscribe to new connectionDetails that can be emitted as part of the RTN24
     this.gcGracePeriod =
-      this._channel.connectionManager.connectionDetails?.objectsGCGracePeriod ?? DEFAULTS.gcGracePeriod;
+      this._channel.connectionManager.connectionDetails?.objectsGCGracePeriod ?? DEFAULTS.gcGracePeriod; // RTO10b1
     this._channel.connectionManager.on('connectiondetails', (details: Record<string, any>) => {
-      this.gcGracePeriod = details.objectsGCGracePeriod ?? DEFAULTS.gcGracePeriod;
+      this.gcGracePeriod = details.objectsGCGracePeriod ?? DEFAULTS.gcGracePeriod; // RTO10b2
     });
   }
 
diff --git a/src/plugins/objects/objectspool.ts b/src/plugins/objects/objectspool.ts
@@ -21,6 +21,7 @@ export class ObjectsPool {
     this._client = this._objects.getClient();
     this._pool = this._createInitialPool();
     this._gcInterval = setInterval(() => {
+      // RTO10
       this._onGCInterval();
     }, DEFAULTS.gcInterval);
     // call nodejs's Timeout.unref to not require Node.js event loop to remain active due to this interval. see https://nodejs.org/api/timers.html#timeoutunref
@@ -103,18 +104,20 @@ export class ObjectsPool {
     return pool;
   }
 
+  /** @spec RTO10c */
   private _onGCInterval(): void {
     const toDelete: string[] = [];
     for (const [objectId, obj] of this._pool.entries()) {
+      // RTO10c1
       // tombstoned objects should be removed from the pool if they have been tombstoned for longer than grace period.
       // by removing them from the local pool, Objects plugin no longer keeps a reference to those objects, allowing JS's
       // Garbage Collection to eventually free the memory for those objects, provided the user no longer references them either.
       if (obj.isTombstoned() && Date.now() - obj.tombstonedAt()! >= this._objects.gcGracePeriod) {
-        toDelete.push(objectId);
+        toDelete.push(objectId); // RTO10c1b
         continue;
       }
 
-      obj.onGCInterval();
+      obj.onGCInterval(); // RTO10c1a
     }
 
     toDelete.forEach((x) => this._pool.delete(x));
