[ECO-5482] Annotated objects realtime API with relevant spec ids

Author: sacOO7

lib/src/main/java/io/ably/lib/objects/LiveObjects.java

@@ -4,7 +4,6 @@
 import io.ably.lib.objects.type.counter.LiveCounter;
 import io.ably.lib.objects.type.map.LiveMap;
 import io.ably.lib.objects.type.map.LiveMapValue;
-import io.ably.lib.types.Callback;
 import org.jetbrains.annotations.Blocking;
 import org.jetbrains.annotations.NonBlocking;
 import org.jetbrains.annotations.NotNull;

live-objects/src/main/kotlin/io/ably/lib/objects/DefaultLiveObjects.kt

@@ -98,19 +98,19 @@ internal class DefaultLiveObjects(internal val channelName: String, internal val
   }
 
   private suspend fun createMapAsync(entries: MutableMap<String, LiveMapValue>): LiveMap {
-    adapter.throwIfInvalidWriteApiConfiguration(channelName)
+    adapter.throwIfInvalidWriteApiConfiguration(channelName) // RTO11c, RTO11d, RTO11e
 
-    if (entries.keys.any { it.isEmpty() }) {
-      throw objectError("Map keys should not be empty")
+    if (entries.keys.any { it.isEmpty() }) { // RTO11f2
+      throw invalidInputError("Map keys should not be empty")
     }
 
-    // Create initial value operation
+    // RTO11f4 - Create initial value operation
     val initialMapValue = DefaultLiveMap.initialValue(entries)
 
-    // Create initial value JSON string
+    // RTO11f5 - Create initial value JSON string
     val initialValueJSONString = gson.toJson(initialMapValue)
 
-    // Create object ID from initial value
+    // RTO11f8 - Create object ID from initial value
     val (objectId, nonce) = getObjectIdStringWithNonce(ObjectType.Map, initialValueJSONString)
 
     // Create ObjectMessage with the operation
@@ -124,28 +124,29 @@ internal class DefaultLiveObjects(internal val channelName: String, internal val
       )
     )
 
-    // Publish the message
+    // RTO11g - Publish the message
     publish(arrayOf(msg))
 
-    // Check if object already exists in pool, otherwise create a zero-value object using the sequential scope
+    // RTO11h - Check if object already exists in pool, otherwise create a zero-value object using the sequential scope
     return objectsPool.get(objectId) as? LiveMap ?: withContext(sequentialScope.coroutineContext) {
       objectsPool.createZeroValueObjectIfNotExists(objectId) as LiveMap
     }
   }
 
   private suspend fun createCounterAsync(initialValue: Number): LiveCounter {
-    adapter.throwIfInvalidWriteApiConfiguration(channelName)
+    adapter.throwIfInvalidWriteApiConfiguration(channelName) // RTO12c, RTO12d, RTO12e
 
     // Validate input parameter
     if (initialValue.toDouble().isNaN() || initialValue.toDouble().isInfinite()) {
-      throw objectError("Counter value should be a valid number")
+      throw invalidInputError("Counter value should be a valid number")
     }
 
+    // RTO12f2
     val initialCounterValue = DefaultLiveCounter.initialValue(initialValue)
-    // Create initial value operation
+    // RTO12f3 - Create initial value operation
     val initialValueJSONString = gson.toJson(initialCounterValue)
 
-    // Create object ID from initial value
+    // RTO12f6- Create object ID from initial value
     val (objectId, nonce) = getObjectIdStringWithNonce(ObjectType.Counter, initialValueJSONString)
 
     // Create ObjectMessage with the operation
@@ -159,15 +160,18 @@ internal class DefaultLiveObjects(internal val channelName: String, internal val
       )
     )
 
-    // Publish the message
+    // RTO12g - Publish the message
     publish(arrayOf(msg))
 
-    // Check if object already exists in pool, otherwise create a zero-value object using the sequential scope
+    // RTO12h - Check if object already exists in pool, otherwise create a zero-value object using the sequential scope
     return objectsPool.get(objectId) as? LiveCounter ?: withContext(sequentialScope.coroutineContext) {
       objectsPool.createZeroValueObjectIfNotExists(objectId) as LiveCounter
     }
   }
 
+  /**
+   * Spec: RTO11f8, RTO12f6
+   */
   private suspend fun getObjectIdStringWithNonce(objectType: ObjectType, initialValue: String): Pair<String, String> {
     val nonce = generateNonce()
     val msTimestamp = ServerTime.getCurrentTime(adapter) // RTO16 - Get server time for nonce generation

live-objects/src/main/kotlin/io/ably/lib/objects/ErrorCodes.kt

@@ -6,7 +6,7 @@ internal enum class ErrorCode(public val code: Int) {
   MaxMessageSizeExceeded(40_009),
   InvalidObject(92_000),
   // LiveMap specific error codes
-  MapKeyShouldBeString(40_003),
+  InvalidInputParams(40_003),
   MapValueDataTypeUnsupported(40_013),
   // Channel mode and state validation error codes
   ChannelModeRequired(40_024),

live-objects/src/main/kotlin/io/ably/lib/objects/ObjectId.kt

@@ -12,15 +12,20 @@ internal class ObjectId private constructor(
 ) {
   /**
    * Converts ObjectId to string representation.
+   * Spec: RTO6b1
    */
   override fun toString(): String {
     return "${type.value}:$hash@$timestampMs"
   }
 
   companion object {
 
+    /**
+     * Spec: RTO14
+     */
     internal fun fromInitialValue(objectType: ObjectType, initialValue: String, nonce: String, msTimeStamp: Long): ObjectId {
       val valueForHash = "$initialValue:$nonce".toByteArray(StandardCharsets.UTF_8)
+      // RTO14b - Hash the initial value and nonce to create a unique identifier
       val hashBytes = MessageDigest.getInstance("SHA-256").digest(valueForHash)
       val urlSafeHash = Base64.getUrlEncoder().withoutPadding().encodeToString(hashBytes)
 

live-objects/src/main/kotlin/io/ably/lib/objects/ServerTime.kt

@@ -7,11 +7,18 @@ import kotlinx.coroutines.sync.withLock
 import kotlinx.coroutines.withContext
 import kotlin.concurrent.Volatile
 
+/**
+ * ServerTime is a utility object that provides the current server time
+ * Spec: RTO16
+ */
 internal object ServerTime {
   @Volatile
   private var serverTimeOffset: Long? = null
   private val mutex = Mutex()
 
+  /**
+   * Spec: RTO16a
+   */
   @Throws(AblyException::class)
   internal suspend fun getCurrentTime(adapter: LiveObjectsAdapter): Long {
     if (serverTimeOffset == null) {

live-objects/src/main/kotlin/io/ably/lib/objects/Utils.kt

@@ -41,6 +41,11 @@ internal fun serverError(errorMessage: String) = ablyException(errorMessage, Err
 internal fun objectError(errorMessage: String, cause: Throwable? = null): AblyException {
   return ablyException(errorMessage, ErrorCode.InvalidObject, HttpStatusCode.InternalServerError, cause)
 }
+
+internal fun invalidInputError(errorMessage: String, cause: Throwable? = null): AblyException {
+  return ablyException(errorMessage, ErrorCode.InvalidInputParams, HttpStatusCode.InternalServerError, cause)
+}
+
 /**
  * Calculates the byte size of a string.
  * For non-ASCII, the byte size can be 2–4x the character count. For ASCII, there is no difference.

live-objects/src/main/kotlin/io/ably/lib/objects/type/livecounter/DefaultLiveCounter.kt

@@ -70,15 +70,15 @@ internal class DefaultLiveCounter private constructor(
   override fun validate(state: ObjectState) = liveCounterManager.validate(state)
 
   private suspend fun incrementAsync(amount: Double) {
-    // Validate write API configuration
+    // RTLC12b, RTLC12c, RTLC12d - Validate write API configuration
     adapter.throwIfInvalidWriteApiConfiguration(channelName)
 
-    // Validate input parameter
+    // RTLC12e1 - Validate input parameter
     if (amount.isNaN() || amount.isInfinite()) {
-      throw objectError("Counter value increment should be a valid number")
+      throw invalidInputError("Counter value increment should be a valid number")
     }
 
-    // Create ObjectMessage with the COUNTER_INC operation
+    // RTLC12e2, RTLC12e3, RTLC12e4 - Create ObjectMessage with the COUNTER_INC operation
     val msg = ObjectMessage(
       operation = ObjectOperation(
         action = ObjectOperationAction.CounterInc,
@@ -87,7 +87,7 @@ internal class DefaultLiveCounter private constructor(
       )
     )
 
-    // Publish the message
+    // RTLC12f - Publish the message
     liveObjects.publish(arrayOf(msg))
   }
 
@@ -127,6 +127,7 @@ internal class DefaultLiveCounter private constructor(
 
     /**
      * Creates initial value operation for counter creation.
+     * Spec: RTO12f2
      */
     internal fun initialValue(count: Number): CounterCreatePayload {
       return CounterCreatePayload(

live-objects/src/main/kotlin/io/ably/lib/objects/type/livemap/DefaultLiveMap.kt

@@ -117,15 +117,15 @@ internal class DefaultLiveMap private constructor(
   override fun unsubscribeAll() = liveMapManager.unsubscribeAll()
 
   private suspend fun setAsync(keyName: String, value: LiveMapValue) {
-    // Validate write API configuration
+    // RTLM20b, RTLM20c, RTLM20d - Validate write API configuration
     adapter.throwIfInvalidWriteApiConfiguration(channelName)
 
     // Validate input parameters
     if (keyName.isEmpty()) {
-      throw objectError("Map key should not be empty")
+      throw invalidInputError("Map key should not be empty")
     }
 
-    // Create ObjectMessage with the MAP_SET operation
+    // RTLM20e - Create ObjectMessage with the MAP_SET operation
     val msg = ObjectMessage(
       operation = ObjectOperation(
         action = ObjectOperationAction.MapSet,
@@ -137,20 +137,20 @@ internal class DefaultLiveMap private constructor(
       )
     )
 
-    // Publish the message
+    // RTLM20f - Publish the message
     liveObjects.publish(arrayOf(msg))
   }
 
   private suspend fun removeAsync(keyName: String) {
-    // Validate write API configuration
+    // RTLM21b, RTLM21cm RTLM21d - Validate write API configuration
     adapter.throwIfInvalidWriteApiConfiguration(channelName)
 
     // Validate input parameter
     if (keyName.isEmpty()) {
-      throw objectError("Map key should not be empty")
+      throw invalidInputError("Map key should not be empty")
     }
 
-    // Create ObjectMessage with the MAP_REMOVE operation
+    // RTLM21e - Create ObjectMessage with the MAP_REMOVE operation
     val msg = ObjectMessage(
       operation = ObjectOperation(
         action = ObjectOperationAction.MapRemove,
@@ -159,7 +159,7 @@ internal class DefaultLiveMap private constructor(
       )
     )
 
-    // Publish the message
+    // RTLM21f - Publish the message
     liveObjects.publish(arrayOf(msg))
   }
 
@@ -199,6 +199,7 @@ internal class DefaultLiveMap private constructor(
 
     /**
      * Creates an ObjectMap from map entries.
+     * Spec: RTO11f4
      */
     internal fun initialValue(entries: MutableMap<String, LiveMapValue>): MapCreatePayload {
       return MapCreatePayload(
@@ -214,6 +215,9 @@ internal class DefaultLiveMap private constructor(
       )
     }
 
+    /**
+     * Spec: RTLM20e5
+     */
     private fun fromLiveMapValue(value: LiveMapValue): ObjectData {
       return when {
         value.isLiveMap || value.isLiveCounter -> {