From c2f9b8f657458838d1739f737dfc81dbdb1be5b5 Mon Sep 17 00:00:00 2001
From: Yuan Chen <godec52217@gmail.com>
Date: Wed, 25 Sep 2024 12:02:34 +0200
Subject: [PATCH 1/2] Add `DeviceRegistration.additionalSpecifications`

---
 .../common/application/devices/AltBeacon.kt   |  7 ++-
 .../BLESerialNumberDeviceRegistration.kt      |  6 +-
 .../devices/DefaultDeviceRegistration.kt      |  5 +-
 .../application/devices/DeviceRegistration.kt | 13 +++++
 .../devices/MACAddressDeviceRegistration.kt   |  6 +-
 .../common/application/devices/Website.kt     |  7 ++-
 .../serialization/UnknownDeviceSerializers.kt |  6 +-
 .../serialization/DeviceRegistrationTest.kt   | 58 ++++++++++++-------
 .../deployments/application/ValidationTest.kt |  2 +
 .../common/devices/DeviceRegistration.json    |  3 +-
 .../carp/rpc/GenerateExampleRequests.kt       |  1 +
 11 files changed, 83 insertions(+), 31 deletions(-)

diff --git a/carp.common/src/commonMain/kotlin/dk/cachet/carp/common/application/devices/AltBeacon.kt b/carp.common/src/commonMain/kotlin/dk/cachet/carp/common/application/devices/AltBeacon.kt
index 74e60a14a..63435e17c 100644
--- a/carp.common/src/commonMain/kotlin/dk/cachet/carp/common/application/devices/AltBeacon.kt
+++ b/carp.common/src/commonMain/kotlin/dk/cachet/carp/common/application/devices/AltBeacon.kt
@@ -2,6 +2,7 @@
 
 package dk.cachet.carp.common.application.devices
 
+import dk.cachet.carp.common.application.ApplicationData
 import dk.cachet.carp.common.application.Trilean
 import dk.cachet.carp.common.application.UUID
 import dk.cachet.carp.common.application.data.CarpDataTypes
@@ -78,7 +79,8 @@ data class AltBeaconDeviceRegistration(
      */
     val referenceRssi: Short,
     @Required
-    override val deviceDisplayName: String? = null // TODO: We could map known manufacturerId's to display names.
+    override val deviceDisplayName: String? = null, // TODO: We could map known manufacturerId's to display names.
+    override val additionalSpecifications: ApplicationData? = null
 ) : DeviceRegistration()
 {
     companion object
@@ -134,6 +136,7 @@ class AltBeaconDeviceRegistrationBuilder : DeviceRegistrationBuilder<AltBeaconDe
         majorId,
         minorId,
         referenceRssi,
-        deviceDisplayName
+        deviceDisplayName,
+        additionalSpecifications
     )
 }
diff --git a/carp.common/src/commonMain/kotlin/dk/cachet/carp/common/application/devices/BLESerialNumberDeviceRegistration.kt b/carp.common/src/commonMain/kotlin/dk/cachet/carp/common/application/devices/BLESerialNumberDeviceRegistration.kt
index 0dcda4c86..8aa2a4065 100644
--- a/carp.common/src/commonMain/kotlin/dk/cachet/carp/common/application/devices/BLESerialNumberDeviceRegistration.kt
+++ b/carp.common/src/commonMain/kotlin/dk/cachet/carp/common/application/devices/BLESerialNumberDeviceRegistration.kt
@@ -1,5 +1,6 @@
 package dk.cachet.carp.common.application.devices
 
+import dk.cachet.carp.common.application.ApplicationData
 import dk.cachet.carp.common.infrastructure.serialization.NotSerializable
 import kotlinx.serialization.*
 import kotlin.js.JsExport
@@ -15,7 +16,8 @@ import kotlin.js.JsExport
 data class BLESerialNumberDeviceRegistration(
     val serialNumber: String,
     @Required
-    override val deviceDisplayName: String? = null
+    override val deviceDisplayName: String? = null,
+    override val additionalSpecifications: ApplicationData? = null
 ) : DeviceRegistration()
 {
     init
@@ -41,5 +43,5 @@ class BLESerialNumberDeviceRegistrationBuilder : DeviceRegistrationBuilder<BLESe
     var serialNumber: String = ""
 
     override fun build(): BLESerialNumberDeviceRegistration =
-        BLESerialNumberDeviceRegistration( serialNumber, deviceDisplayName )
+        BLESerialNumberDeviceRegistration( serialNumber, deviceDisplayName, additionalSpecifications )
 }
diff --git a/carp.common/src/commonMain/kotlin/dk/cachet/carp/common/application/devices/DefaultDeviceRegistration.kt b/carp.common/src/commonMain/kotlin/dk/cachet/carp/common/application/devices/DefaultDeviceRegistration.kt
index 3bd05b368..f57efe5b1 100644
--- a/carp.common/src/commonMain/kotlin/dk/cachet/carp/common/application/devices/DefaultDeviceRegistration.kt
+++ b/carp.common/src/commonMain/kotlin/dk/cachet/carp/common/application/devices/DefaultDeviceRegistration.kt
@@ -1,5 +1,6 @@
 package dk.cachet.carp.common.application.devices
 
+import dk.cachet.carp.common.application.ApplicationData
 import dk.cachet.carp.common.application.UUID
 import dk.cachet.carp.common.infrastructure.serialization.NotSerializable
 import kotlinx.serialization.*
@@ -16,6 +17,7 @@ import kotlin.js.JsExport
 data class DefaultDeviceRegistration(
     @Required
     override val deviceDisplayName: String? = null,
+    override val additionalSpecifications: ApplicationData? = null,
     @Required
     override val deviceId: String = UUID.randomUUID().toString()
 ) : DeviceRegistration()
@@ -36,5 +38,6 @@ class DefaultDeviceRegistrationBuilder : DeviceRegistrationBuilder<DefaultDevice
      */
     var deviceId: String = UUID.randomUUID().toString()
 
-    override fun build(): DefaultDeviceRegistration = DefaultDeviceRegistration( deviceDisplayName, deviceId )
+    override fun build(): DefaultDeviceRegistration =
+        DefaultDeviceRegistration( deviceDisplayName, additionalSpecifications, deviceId )
 }
diff --git a/carp.common/src/commonMain/kotlin/dk/cachet/carp/common/application/devices/DeviceRegistration.kt b/carp.common/src/commonMain/kotlin/dk/cachet/carp/common/application/devices/DeviceRegistration.kt
index a6d86a081..ca80fea51 100644
--- a/carp.common/src/commonMain/kotlin/dk/cachet/carp/common/application/devices/DeviceRegistration.kt
+++ b/carp.common/src/commonMain/kotlin/dk/cachet/carp/common/application/devices/DeviceRegistration.kt
@@ -2,6 +2,7 @@
 
 package dk.cachet.carp.common.application.devices
 
+import dk.cachet.carp.common.application.ApplicationData
 import dk.cachet.carp.common.application.Immutable
 import dk.cachet.carp.common.application.ImplementAsDataClass
 import dk.cachet.carp.common.infrastructure.serialization.NotSerializable
@@ -42,6 +43,12 @@ abstract class DeviceRegistration
 
     @Required
     val registrationCreatedOn: Instant = Clock.System.now()
+
+    /**
+     * Additional device specifications which may be relevant to the researcher when interpreting collected data.
+     * E.g., brand/model name, operating system version, or any other relevant information.
+     */
+    abstract val additionalSpecifications: ApplicationData?
 }
 
 
@@ -65,6 +72,12 @@ abstract class DeviceRegistrationBuilder<T : DeviceRegistration>
      */
     var deviceDisplayName: String? = null
 
+    /**
+     * Additional device specifications which may be relevant to the researcher when interpreting collected data.
+     * E.g., brand/model name, operating system version, or any other relevant information.
+     */
+    var additionalSpecifications: ApplicationData? = null
+
     /**
      * Build the immutable [DeviceRegistration] using the current configuration of this [DeviceRegistrationBuilder].
      */
diff --git a/carp.common/src/commonMain/kotlin/dk/cachet/carp/common/application/devices/MACAddressDeviceRegistration.kt b/carp.common/src/commonMain/kotlin/dk/cachet/carp/common/application/devices/MACAddressDeviceRegistration.kt
index 6825872f3..824e41b67 100644
--- a/carp.common/src/commonMain/kotlin/dk/cachet/carp/common/application/devices/MACAddressDeviceRegistration.kt
+++ b/carp.common/src/commonMain/kotlin/dk/cachet/carp/common/application/devices/MACAddressDeviceRegistration.kt
@@ -1,5 +1,6 @@
 package dk.cachet.carp.common.application.devices
 
+import dk.cachet.carp.common.application.ApplicationData
 import dk.cachet.carp.common.application.MACAddress
 import dk.cachet.carp.common.infrastructure.serialization.NotSerializable
 import kotlinx.serialization.*
@@ -14,7 +15,8 @@ import kotlin.js.JsExport
 data class MACAddressDeviceRegistration(
     val macAddress: MACAddress,
     @Required
-    override val deviceDisplayName: String? = null
+    override val deviceDisplayName: String? = null,
+    override val additionalSpecifications: ApplicationData? = null
 ) : DeviceRegistration()
 {
     @Required
@@ -30,5 +32,5 @@ class MACAddressDeviceRegistrationBuilder : DeviceRegistrationBuilder<MACAddress
     var macAddress: String = ""
 
     override fun build(): MACAddressDeviceRegistration =
-        MACAddressDeviceRegistration( MACAddress.parse( macAddress ), deviceDisplayName )
+        MACAddressDeviceRegistration( MACAddress.parse( macAddress ), deviceDisplayName, additionalSpecifications )
 }
diff --git a/carp.common/src/commonMain/kotlin/dk/cachet/carp/common/application/devices/Website.kt b/carp.common/src/commonMain/kotlin/dk/cachet/carp/common/application/devices/Website.kt
index 28b0f5716..e0f178bf7 100644
--- a/carp.common/src/commonMain/kotlin/dk/cachet/carp/common/application/devices/Website.kt
+++ b/carp.common/src/commonMain/kotlin/dk/cachet/carp/common/application/devices/Website.kt
@@ -2,6 +2,7 @@
 
 package dk.cachet.carp.common.application.devices
 
+import dk.cachet.carp.common.application.ApplicationData
 import dk.cachet.carp.common.application.Trilean
 import dk.cachet.carp.common.application.data.DataType
 import dk.cachet.carp.common.application.sampling.DataTypeSamplingSchemeMap
@@ -51,7 +52,8 @@ data class WebsiteDeviceRegistration(
      */
     val userAgent: String,
     @Required
-    override val deviceDisplayName: String? = userAgent
+    override val deviceDisplayName: String? = userAgent,
+    override val additionalSpecifications: ApplicationData? = null
 ) : DeviceRegistration()
 {
     @Required
@@ -74,5 +76,6 @@ class WebsiteDeviceRegistrationBuilder : DeviceRegistrationBuilder<WebsiteDevice
      */
     var userAgent: String = ""
 
-    override fun build(): WebsiteDeviceRegistration = WebsiteDeviceRegistration( url, userAgent, deviceDisplayName )
+    override fun build(): WebsiteDeviceRegistration =
+        WebsiteDeviceRegistration( url, userAgent, deviceDisplayName, additionalSpecifications )
 }
diff --git a/carp.common/src/commonMain/kotlin/dk/cachet/carp/common/infrastructure/serialization/UnknownDeviceSerializers.kt b/carp.common/src/commonMain/kotlin/dk/cachet/carp/common/infrastructure/serialization/UnknownDeviceSerializers.kt
index 21e48b9fe..3a9eb67c3 100644
--- a/carp.common/src/commonMain/kotlin/dk/cachet/carp/common/infrastructure/serialization/UnknownDeviceSerializers.kt
+++ b/carp.common/src/commonMain/kotlin/dk/cachet/carp/common/infrastructure/serialization/UnknownDeviceSerializers.kt
@@ -1,5 +1,6 @@
 package dk.cachet.carp.common.infrastructure.serialization
 
+import dk.cachet.carp.common.application.ApplicationData
 import dk.cachet.carp.common.application.Trilean
 import dk.cachet.carp.common.application.data.DataType
 import dk.cachet.carp.common.application.devices.AnyDeviceConfiguration
@@ -178,11 +179,13 @@ data class CustomDeviceRegistration internal constructor(
     @Serializable
     private data class BaseMembers(
         override val deviceId: String,
-        override val deviceDisplayName: String?
+        override val deviceDisplayName: String?,
+        override val additionalSpecifications: ApplicationData? = null
     ) : DeviceRegistration()
 
     override val deviceId: String
     override val deviceDisplayName: String?
+    override val additionalSpecifications: ApplicationData?
 
     init
     {
@@ -190,6 +193,7 @@ data class CustomDeviceRegistration internal constructor(
         val baseMembers = json.decodeFromString( BaseMembers.serializer(), jsonSource )
         deviceId = baseMembers.deviceId
         deviceDisplayName = baseMembers.deviceDisplayName
+        additionalSpecifications = baseMembers.additionalSpecifications
     }
 }
 
diff --git a/carp.common/src/commonTest/kotlin/dk/cachet/carp/common/infrastructure/serialization/DeviceRegistrationTest.kt b/carp.common/src/commonTest/kotlin/dk/cachet/carp/common/infrastructure/serialization/DeviceRegistrationTest.kt
index e0537305f..5e098dd25 100644
--- a/carp.common/src/commonTest/kotlin/dk/cachet/carp/common/infrastructure/serialization/DeviceRegistrationTest.kt
+++ b/carp.common/src/commonTest/kotlin/dk/cachet/carp/common/infrastructure/serialization/DeviceRegistrationTest.kt
@@ -1,9 +1,10 @@
 package dk.cachet.carp.common.infrastructure.serialization
 
+import dk.cachet.carp.common.application.ApplicationData
 import dk.cachet.carp.common.application.devices.DefaultDeviceRegistration
 import dk.cachet.carp.common.application.devices.DeviceRegistration
-import kotlinx.serialization.decodeFromString
-import kotlinx.serialization.encodeToString
+import dk.cachet.carp.common.infrastructure.test.makeUnknown
+import kotlinx.serialization.*
 import kotlin.test.*
 
 
@@ -15,12 +16,12 @@ class DeviceRegistrationTest
     @Test
     fun can_serialize_and_deserialize_device_registration_using_JSON()
     {
-        val default: DeviceRegistration = DefaultDeviceRegistration()
-
-        val serialized = testJson.encodeToString( DeviceRegistration.serializer(), default )
-        val parsed: DeviceRegistration = testJson.decodeFromString( serialized )
-
-        assertEquals( default, parsed )
+        val toSerialize = getTestCases()
+        toSerialize.forEach {
+            val serialized = testJson.encodeToString( DeviceRegistration.serializer(), it )
+            val parsed: DeviceRegistration = testJson.decodeFromString( serialized )
+            assertEquals( it, parsed )
+        }
     }
 
     /**
@@ -29,10 +30,12 @@ class DeviceRegistrationTest
     @Test
     fun unknown_types_are_wrapped_when_deserializing()
     {
-        val unknownRegistration = serializeUnknownDeviceRegistration()
-        val parsed: DeviceRegistration = testJson.decodeFromString( unknownRegistration )
-
-        assertTrue( parsed is CustomDeviceRegistration )
+        val toSerialize = getTestCases()
+        toSerialize.forEach {
+            val unknownRegistration = serializeUnknownDeviceRegistration( it )
+            val parsed: DeviceRegistration = testJson.decodeFromString( unknownRegistration )
+            assertTrue( parsed is CustomDeviceRegistration )
+        }
     }
 
     /**
@@ -41,18 +44,33 @@ class DeviceRegistrationTest
     @Test
     fun serializing_unknown_types_removes_the_wrapper()
     {
-        val unknownRegistration = serializeUnknownDeviceRegistration()
-        val parsed: DeviceRegistration = testJson.decodeFromString( unknownRegistration )
-
-        val serialized = testJson.encodeToString( parsed )
-        assertEquals( unknownRegistration, serialized )
+        val toSerialize = getTestCases()
+        toSerialize.forEach {
+            val unknownRegistration = serializeUnknownDeviceRegistration( it )
+            val parsed: DeviceRegistration = testJson.decodeFromString( unknownRegistration )
+            val serialized = testJson.encodeToString( parsed )
+            assertEquals( unknownRegistration, serialized )
+        }
     }
 
-    private fun serializeUnknownDeviceRegistration(): String
+    private fun getTestCases() = listOf(
+        // With null values.
+        DefaultDeviceRegistration(),
+
+        // With all nullable fields set.
+        DefaultDeviceRegistration(
+            deviceDisplayName = "Device name",
+            additionalSpecifications = ApplicationData( """{"OS":"Android 42"}""" )
+        )
+    )
+
+    /**
+     * Serialize [registration] as an unknown type using JSON.
+     */
+    private fun serializeUnknownDeviceRegistration( registration: DeviceRegistration ): String
     {
-        val registration = DefaultDeviceRegistration()
         var serialized = testJson.encodeToString( DeviceRegistration.serializer(), registration )
-        serialized = serialized.replace( "dk.cachet.carp.common.application.devices.DefaultDeviceRegistration", "com.unknown.CustomRegistration" )
+        serialized = serialized.makeUnknown( registration )
 
         return serialized
     }
diff --git a/carp.deployments.core/src/commonTest/kotlin/dk/cachet/carp/deployments/application/ValidationTest.kt b/carp.deployments.core/src/commonTest/kotlin/dk/cachet/carp/deployments/application/ValidationTest.kt
index 9b9e9d147..1986590e0 100644
--- a/carp.deployments.core/src/commonTest/kotlin/dk/cachet/carp/deployments/application/ValidationTest.kt
+++ b/carp.deployments.core/src/commonTest/kotlin/dk/cachet/carp/deployments/application/ValidationTest.kt
@@ -1,5 +1,6 @@
 package dk.cachet.carp.deployments.application
 
+import dk.cachet.carp.common.application.ApplicationData
 import dk.cachet.carp.common.application.UUID
 import dk.cachet.carp.common.application.devices.DefaultDeviceRegistration
 import dk.cachet.carp.common.application.devices.DeviceRegistration
@@ -158,6 +159,7 @@ class ValidationTest
             {
                 override val deviceId: String = "Invalid"
                 override val deviceDisplayName: String? = null
+                override val additionalSpecifications: ApplicationData? = null
             }
         val preregistrations = mapOf( connectedRoleName to invalidRegistration )
 
diff --git a/rpc/schemas/common/devices/DeviceRegistration.json b/rpc/schemas/common/devices/DeviceRegistration.json
index b9a1cdc7f..f8c30cee5 100644
--- a/rpc/schemas/common/devices/DeviceRegistration.json
+++ b/rpc/schemas/common/devices/DeviceRegistration.json
@@ -31,7 +31,8 @@
         "__type": true,
         "deviceId": { "type": "string" },
         "deviceDisplayName": { "type": [ "string", "null" ] },
-        "registrationCreatedOn": { "type": "string", "format": "date-time" }
+        "registrationCreatedOn": { "type": "string", "format": "date-time" },
+        "additionalSpecifications": { "$ref":  "../../common/ApplicationData.json" }
       },
       "required": [ "__type", "deviceId", "deviceDisplayName", "registrationCreatedOn" ]
     }
diff --git a/rpc/src/main/kotlin/dk/cachet/carp/rpc/GenerateExampleRequests.kt b/rpc/src/main/kotlin/dk/cachet/carp/rpc/GenerateExampleRequests.kt
index 3391a421c..8b02b9d97 100644
--- a/rpc/src/main/kotlin/dk/cachet/carp/rpc/GenerateExampleRequests.kt
+++ b/rpc/src/main/kotlin/dk/cachet/carp/rpc/GenerateExampleRequests.kt
@@ -187,6 +187,7 @@ private val bikeBeaconPreregistration = bikeBeacon.createRegistration {
     organizationId = UUID( "4e990957-0838-414c-bf25-2d391e2990b5" )
     majorId = 42
     minorId = 42
+    additionalSpecifications = ApplicationData( """{"Model": "AnyBeacon B42"}""" )
 }.setRegistrationCreatedOn( deploymentCreatedOn )
 private val phoneRegistration = phone.createRegistration {
     deviceId = UUID( "fc7b41b0-e9e2-4b5d-8c3d-5119b556a3f0" ).toString()

From 1de2e41e2352e0bad70af342d0f97e5b12a17e99 Mon Sep 17 00:00:00 2001
From: Yuan Chen <godec52217@gmail.com>
Date: Fri, 27 Sep 2024 15:28:33 +0200
Subject: [PATCH 2/2] Remove unused workaround for former serialization bug

---
 .../deployments/application/PrimaryDeviceDeployment.kt | 10 +---------
 1 file changed, 1 insertion(+), 9 deletions(-)

diff --git a/carp.deployments.core/src/commonMain/kotlin/dk/cachet/carp/deployments/application/PrimaryDeviceDeployment.kt b/carp.deployments.core/src/commonMain/kotlin/dk/cachet/carp/deployments/application/PrimaryDeviceDeployment.kt
index a204027f1..eec0df5b1 100644
--- a/carp.deployments.core/src/commonMain/kotlin/dk/cachet/carp/deployments/application/PrimaryDeviceDeployment.kt
+++ b/carp.deployments.core/src/commonMain/kotlin/dk/cachet/carp/deployments/application/PrimaryDeviceDeployment.kt
@@ -14,7 +14,6 @@ import dk.cachet.carp.common.application.triggers.TaskControl
 import dk.cachet.carp.common.application.triggers.TriggerConfiguration
 import dk.cachet.carp.common.application.users.ExpectedParticipantData
 import dk.cachet.carp.common.application.users.hasNoConflicts
-import kotlinx.datetime.Clock
 import kotlinx.datetime.Instant
 import kotlinx.serialization.*
 import kotlin.js.JsExport
@@ -97,14 +96,7 @@ data class PrimaryDeviceDeployment(
      * The time when this device deployment was last updated.
      * This corresponds to the most recent device registration as part of this device deployment.
      */
-    val lastUpdatedOn: Instant =
-        // TODO: Remove this workaround once JS serialization bug is fixed:
-        //  https://github.com/Kotlin/kotlinx.serialization/issues/716
-        @Suppress( "SENSELESS_COMPARISON" )
-        if ( connectedDeviceRegistrations == null || registration == null ) Clock.System.now()
-        else connectedDeviceRegistrations.values.plus( registration )
-            .maxOf { it.registrationCreatedOn }
-
+    val lastUpdatedOn: Instant = (connectedDeviceRegistrations.values + registration).maxOf { it.registrationCreatedOn }
 
     /**
      * Get info on the primary device and each of the devices this device needs to connect to relevant at study runtime.