Merge pull request #2044 from ably/objects-spec-tags

Objects spec tags: ObjectMessage and sync sequence

Author: VeskeR

src/common/lib/client/modularplugins.ts

@@ -41,7 +41,7 @@ export interface ModularPlugins {
   FetchRequest?: typeof fetchRequest;
   MessageInteractions?: typeof FilteredSubscriptions;
   Push?: typeof PushPlugin;
-  Objects?: typeof ObjectsPlugin;
+  Objects?: typeof ObjectsPlugin; // PC5, PT2b
 }
 
 export const allCommonModularPlugins: ModularPlugins = { Rest };

src/common/lib/client/realtimechannel.ts

@@ -149,11 +149,12 @@ class RealtimeChannel extends EventEmitter {
     return this._push;
   }
 
+  /** @spec RTL27 */
   get objects() {
     if (!this._objects) {
-      Utils.throwMissingPluginError('Objects');
+      Utils.throwMissingPluginError('Objects'); // RTL27b
     }
-    return this._objects;
+    return this._objects; // RTL27a
   }
 
   invalidStateError(): ErrorInfo {
@@ -613,6 +614,7 @@ class RealtimeChannel extends EventEmitter {
         break;
       }
 
+      // RTL1
       // OBJECT and OBJECT_SYNC message processing share most of the logic, so group them together
       case actions.OBJECT:
       case actions.OBJECT_SYNC: {

src/common/lib/types/protocolmessage.ts

@@ -169,7 +169,7 @@ class ProtocolMessage {
   /**
    * This will be undefined if we skipped decoding this property due to user not requesting Objects functionality — see {@link fromDeserialized}
    */
-  state?: ObjectsPlugin.ObjectMessage[];
+  state?: ObjectsPlugin.ObjectMessage[]; // TR4r
   auth?: unknown;
   connectionDetails?: Record<string, unknown>;
   params?: Record<string, string>;

src/common/lib/types/protocolmessagecommon.ts

@@ -1,6 +1,7 @@
 // constant definitions that can be imported by anyone without worrying about circular
 // deps
 
+// TR2
 export const actions = {
   HEARTBEAT: 0,
   ACK: 1,
@@ -31,6 +32,7 @@ Object.keys(actions).forEach(function (name) {
   ActionName[(actions as { [key: string]: number })[name]] = name;
 });
 
+// TR3
 export const flags: { [key: string]: number } = {
   /* Channel attach state flags */
   HAS_PRESENCE: 1 << 0,

src/common/lib/util/utils.ts

@@ -285,8 +285,8 @@ export function inspectBody(body: unknown): string {
  * Returns the byte size of the provided data based on the spec:
  * - TM6a - size of the string is byte length of the string
  * - TM6c - size of the buffer is its size in bytes
- * - OD3c - size of a number is 8 bytes
- * - OD3d - size of a boolean is 1 byte
+ * - OD3d - size of a number is 8 bytes
+ * - OD3b - size of a boolean is 1 byte
  */
 export function dataSizeBytes(data: string | number | boolean | Bufferlike): number {
   if (Platform.BufferUtils.isBuffer(data)) {

src/plugins/objects/livecounter.ts

@@ -4,18 +4,20 @@ import { ObjectMessage, ObjectOperation, ObjectOperationAction, ObjectsCounterOp
 import { Objects } from './objects';
 
 export interface LiveCounterData extends LiveObjectData {
-  data: number;
+  data: number; // RTLC3
 }
 
 export interface LiveCounterUpdate extends LiveObjectUpdate {
   update: { amount: number };
 }
 
+/** @spec RTLC1, RTLC2 */
 export class LiveCounter extends LiveObject<LiveCounterData, LiveCounterUpdate> {
   /**
    * Returns a {@link LiveCounter} instance with a 0 value.
    *
    * @internal
+   * @spec RTLC4
    */
   static zeroValue(objects: Objects, objectId: string): LiveCounter {
     return new LiveCounter(objects, objectId);
@@ -122,9 +124,10 @@ export class LiveCounter extends LiveObject<LiveCounterData, LiveCounterUpdate>
     };
   }
 
+  /** @spec RTLC5 */
   value(): number {
-    this._objects.throwIfInvalidAccessApiConfiguration();
-    return this._dataRef.data;
+    this._objects.throwIfInvalidAccessApiConfiguration(); // RTLC5a, RTLC5b
+    return this._dataRef.data; // RTLC5c
   }
 
   /**
@@ -221,6 +224,7 @@ export class LiveCounter extends LiveObject<LiveCounterData, LiveCounterUpdate>
 
   /**
    * @internal
+   * @spec RTLC6
    */
   overrideWithObjectState(objectState: ObjectState): LiveCounterUpdate | LiveObjectUpdateNoop {
     if (objectState.objectId !== this.getObjectId()) {
@@ -252,7 +256,7 @@ export class LiveCounter extends LiveObject<LiveCounterData, LiveCounterUpdate>
 
     // object's site serials are still updated even if it is tombstoned, so always use the site serials received from the operation.
     // should default to empty map if site serials do not exist on the object state, so that any future operation may be applied to this object.
-    this._siteTimeserials = objectState.siteTimeserials ?? {};
+    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
@@ -265,8 +269,9 @@ export class LiveCounter extends LiveObject<LiveCounterData, LiveCounterUpdate>
       this.tombstone();
     } else {
       // override data for this object with data from the object state
-      this._createOperationIsMerged = false;
-      this._dataRef = { data: objectState.counter?.count ?? 0 };
+      this._createOperationIsMerged = false; // RTLC6b
+      this._dataRef = { data: objectState.counter?.count ?? 0 }; // RTLC6c
+      // RTLC6d
       if (!this._client.Utils.isNil(objectState.createOp)) {
         this._mergeInitialDataFromCreateOperation(objectState.createOp);
       }
@@ -285,6 +290,7 @@ export class LiveCounter extends LiveObject<LiveCounterData, LiveCounterUpdate>
     return;
   }
 
+  /** @spec RTLC4 */
   protected _getZeroValueData(): LiveCounterData {
     return { data: 0 };
   }
@@ -299,8 +305,8 @@ export class LiveCounter extends LiveObject<LiveCounterData, LiveCounterUpdate>
     // 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;
-    this._createOperationIsMerged = true;
+    this._dataRef.data += objectOperation.counter?.count ?? 0; // RTLC6d1
+    this._createOperationIsMerged = true; // RTLC6d2
 
     return { update: { amount: objectOperation.counter?.count ?? 0 } };
   }