Add .serialName to MissingFieldException

Make new constructor that requires it, and allow creation with nullable serial name only via internal mechanism.

Old constructor without serial name should be eventually hidden.

Fixes #2958

Author: sandwwraith

core/api/kotlinx-serialization-core.api

@@ -51,11 +51,12 @@ public abstract interface annotation class kotlinx/serialization/MetaSerializabl
 }
 
 public final class kotlinx/serialization/MissingFieldException : kotlinx/serialization/SerializationException {
-	public fun <init> (Ljava/lang/String;)V
+	public synthetic fun <init> (Ljava/lang/String;)V
 	public fun <init> (Ljava/lang/String;Ljava/lang/String;)V
 	public fun <init> (Ljava/util/List;Ljava/lang/String;)V
 	public fun <init> (Ljava/util/List;Ljava/lang/String;Ljava/lang/Throwable;)V
 	public final fun getMissingFields ()Ljava/util/List;
+	public final fun getSerialName ()Ljava/lang/String;
 }
 
 public abstract interface annotation class kotlinx/serialization/Polymorphic : java/lang/annotation/Annotation {
@@ -848,6 +849,7 @@ public final class kotlinx/serialization/internal/IntSerializer : kotlinx/serial
 
 public final class kotlinx/serialization/internal/JsonInternalDependenciesKt {
 	public static final fun jsonCachedSerialNames (Lkotlinx/serialization/descriptors/SerialDescriptor;)Ljava/util/Set;
+	public static final fun missingFieldExceptionWithNewMessage (Lkotlinx/serialization/MissingFieldException;Ljava/lang/String;)Lkotlinx/serialization/MissingFieldException;
 }
 
 public abstract class kotlinx/serialization/internal/KeyValueSerializer : kotlinx/serialization/KSerializer {

core/api/kotlinx-serialization-core.klib.api

@@ -743,6 +743,8 @@ final class kotlinx.serialization/MissingFieldException : kotlinx.serialization/
 
     final val missingFields // kotlinx.serialization/MissingFieldException.missingFields|{}missingFields[0]
         final fun <get-missingFields>(): kotlin.collections/List<kotlin/String> // kotlinx.serialization/MissingFieldException.missingFields.<get-missingFields>|<get-missingFields>(){}[0]
+    final val serialName // kotlinx.serialization/MissingFieldException.serialName|{}serialName[0]
+        final fun <get-serialName>(): kotlin/String? // kotlinx.serialization/MissingFieldException.serialName.<get-serialName>|<get-serialName>(){}[0]
 }
 
 final class kotlinx.serialization/UnknownFieldException : kotlinx.serialization/SerializationException { // kotlinx.serialization/UnknownFieldException|null[0]
@@ -1153,6 +1155,7 @@ final fun kotlinx.serialization.descriptors/listSerialDescriptor(kotlinx.seriali
 final fun kotlinx.serialization.descriptors/mapSerialDescriptor(kotlinx.serialization.descriptors/SerialDescriptor, kotlinx.serialization.descriptors/SerialDescriptor): kotlinx.serialization.descriptors/SerialDescriptor // kotlinx.serialization.descriptors/mapSerialDescriptor|mapSerialDescriptor(kotlinx.serialization.descriptors.SerialDescriptor;kotlinx.serialization.descriptors.SerialDescriptor){}[0]
 final fun kotlinx.serialization.descriptors/serialDescriptor(kotlin.reflect/KType): kotlinx.serialization.descriptors/SerialDescriptor // kotlinx.serialization.descriptors/serialDescriptor|serialDescriptor(kotlin.reflect.KType){}[0]
 final fun kotlinx.serialization.descriptors/setSerialDescriptor(kotlinx.serialization.descriptors/SerialDescriptor): kotlinx.serialization.descriptors/SerialDescriptor // kotlinx.serialization.descriptors/setSerialDescriptor|setSerialDescriptor(kotlinx.serialization.descriptors.SerialDescriptor){}[0]
+final fun kotlinx.serialization.internal/missingFieldExceptionWithNewMessage(kotlinx.serialization/MissingFieldException, kotlin/String): kotlinx.serialization/MissingFieldException // kotlinx.serialization.internal/missingFieldExceptionWithNewMessage|missingFieldExceptionWithNewMessage(kotlinx.serialization.MissingFieldException;kotlin.String){}[0]
 final fun kotlinx.serialization.internal/throwArrayMissingFieldException(kotlin/IntArray, kotlin/IntArray, kotlinx.serialization.descriptors/SerialDescriptor) // kotlinx.serialization.internal/throwArrayMissingFieldException|throwArrayMissingFieldException(kotlin.IntArray;kotlin.IntArray;kotlinx.serialization.descriptors.SerialDescriptor){}[0]
 final fun kotlinx.serialization.internal/throwMissingFieldException(kotlin/Int, kotlin/Int, kotlinx.serialization.descriptors/SerialDescriptor) // kotlinx.serialization.internal/throwMissingFieldException|throwMissingFieldException(kotlin.Int;kotlin.Int;kotlinx.serialization.descriptors.SerialDescriptor){}[0]
 final fun kotlinx.serialization.modules/EmptySerializersModule(): kotlinx.serialization.modules/SerializersModule // kotlinx.serialization.modules/EmptySerializersModule|EmptySerializersModule(){}[0]

core/commonMain/src/kotlinx/serialization/SerializationExceptions.kt

@@ -71,15 +71,17 @@ public open class SerializationException : IllegalArgumentException {
  * [MissingFieldException] is constructed from the following properties:
  * - [missingFields] -- fields that were required for the deserialization but have not been found.
  *   They are always non-empty and their names match the corresponding names in [SerialDescriptor.elementNames]
- * - Optional `serialName` -- serial name of the enclosing class that failed to get deserialized.
+ * - [serialName] -- a serial name of the enclosing class that failed to get deserialized.
  *   Matches the corresponding [SerialDescriptor.serialName].
  *
  * @see SerializationException
  * @see KSerializer
  */
 @ExperimentalSerializationApi
-public class MissingFieldException(
-    missingFields: List<String>, message: String?, cause: Throwable?
+public class MissingFieldException private constructor(
+    // only private constructor allows nullable serialName and message
+    // reordered things a bit to avoid signature clash with public one
+    message: String?, cause: Throwable?, missingFields: List<String>, serialName: String?
 ) : SerializationException(message, cause) {
 
     /**
@@ -88,6 +90,15 @@ public class MissingFieldException(
      */
     public val missingFields: List<String> = missingFields
 
+    /**
+     * Returns a serial name of a serializable class that cannot be deserialized due to missing fields.
+     * Typically, equal to the [SerialDescriptor.serialName] of the serializable class.
+     *
+     * However, in cases the class was compiled with an old Kotlin serialization plugin,
+     * its serial name may be unavailable and this property is `null`.
+     */
+    public val serialName: String? = serialName
+
     /**
      * Creates an instance of [MissingFieldException] for the given [missingFields] and [serialName] of
      * the corresponding serializer.
@@ -96,10 +107,11 @@ public class MissingFieldException(
         missingFields: List<String>,
         serialName: String
     ) : this(
-        missingFields,
-        if (missingFields.size == 1) "Field '${missingFields[0]}' is required for type with serial name '$serialName', but it was missing"
+        missingFields = missingFields,
+        serialName = serialName,
+        message = if (missingFields.size == 1) "Field '${missingFields[0]}' is required for type with serial name '$serialName', but it was missing"
         else "Fields $missingFields are required for type with serial name '$serialName', but they were missing",
-        null
+        cause = null
     )
 
     /**
@@ -110,16 +122,33 @@ public class MissingFieldException(
         missingField: String,
         serialName: String
     ) : this(
-        listOf(missingField),
-        "Field '$missingField' is required for type with serial name '$serialName', but it was missing",
-        null
+        missingFields = listOf(missingField),
+        serialName = serialName,
+        message = "Field '$missingField' is required for type with serial name '$serialName', but it was missing",
+        cause = null
     )
 
-    @PublishedApi // Constructor used by the generated serializers
+    // Deprecated since 1.10.0, should be HIDDEN when MFE is stable
+    @Deprecated("Use constructor which accepts serialName parameter", ReplaceWith("MissingFieldException(missingFields, descriptor.serialName, message, cause)"), level = DeprecationLevel.ERROR)
+    public constructor(
+        missingFields: List<String>, message: String?, cause: Throwable?
+    ) : this(message, cause, missingFields, serialName = null)
+
+    @PublishedApi
+    @Deprecated("Constructor used by the serializers generated by plugins older than Kotlin 1.5", level = DeprecationLevel.HIDDEN)
     internal constructor(missingField: String) : this(
-        listOf(missingField),
-        "Field '$missingField' is required, but it was missing",
-        null
+        message = "Field '$missingField' is required, but it was missing",
+        cause = null,
+        missingFields = listOf(missingField),
+        serialName = null
+    )
+
+    // It's better to have internal function calling private ctor rather than just internal ctor (because the latter is visible from Java)
+    internal fun withNewMessageInternal(newMessage: String): MissingFieldException = MissingFieldException(
+        message = newMessage,
+        cause = this,
+        missingFields = missingFields,
+        serialName = serialName
     )
 }
 

core/commonMain/src/kotlinx/serialization/internal/JsonInternalDependencies.kt

@@ -1,14 +1,21 @@
 package kotlinx.serialization.internal
 
+import kotlinx.serialization.ExperimentalSerializationApi
+import kotlinx.serialization.MissingFieldException
 import kotlinx.serialization.descriptors.*
 
 /*
  * Methods that are required for kotlinx-serialization-json, but are not effectively public.
  *
- * Anything marker with this annotation is not intended for public use.
+ * Anything marked with this annotation is not intended for public use.
  */
 @RequiresOptIn(level = RequiresOptIn.Level.ERROR)
 internal annotation class CoreFriendModuleApi
 
 @CoreFriendModuleApi
 public fun SerialDescriptor.jsonCachedSerialNames(): Set<String> = cachedSerialNames()
+
+@ExperimentalSerializationApi
+@CoreFriendModuleApi
+public fun missingFieldExceptionWithNewMessage(exception: MissingFieldException, message: String): MissingFieldException =
+    exception.withNewMessageInternal(message)

formats/json-tests/jvmTest/src/kotlinx/serialization/JvmMissingFieldsExceptionTest.kt

@@ -2,6 +2,7 @@ package kotlinx.serialization
 
 import org.junit.Test
 import kotlinx.serialization.json.Json
+import kotlinx.serialization.builtins.serializer
 import kotlinx.serialization.modules.SerializersModule
 import kotlinx.serialization.modules.polymorphic
 import kotlinx.serialization.modules.subclass
@@ -74,7 +75,10 @@ class JvmMissingFieldsExceptionTest {
 
     @Test
     fun testShortPlaneClass() {
-        assertFailsWithMessages(listOf("f2", "f4")) {
+        assertFailsWithMessages(
+            fields = listOf("f2", "f4"),
+            expectedSerialName = ShortPlaneClass.serializer().descriptor.serialName
+        ) {
             Json.decodeFromString<ShortPlaneClass>("""{"f1":1}""")
         }
     }
@@ -86,7 +90,10 @@ class JvmMissingFieldsExceptionTest {
         val optionalFields = arrayOf("f3", "f5", "f7")
         missedFields.removeAll(definedInJsonFields)
         missedFields.removeAll(optionalFields)
-        assertFailsWithMessages(missedFields) {
+        assertFailsWithMessages(
+            fields = missedFields,
+            expectedSerialName = BigPlaneClass.serializer().descriptor.serialName
+        ) {
             Json.decodeFromString<BigPlaneClass>("""{"f1":1, "f15": 15, "f34": 34}""")
         }
     }
@@ -102,38 +109,56 @@ class JvmMissingFieldsExceptionTest {
             serializersModule = module
         }
 
-        assertFailsWithMessages(listOf("p2", "c3")) {
+        assertFailsWithMessages(
+            fields = listOf("p2", "c3"),
+            // For polymorphic, the error originates from the actual subtype
+            expectedSerialName = ChildA.serializer().descriptor.serialName
+        ) {
             json.decodeFromString<PolymorphicWrapper>("""{"nested": {"type": "a", "p1": 1, "c1": 11}}""")
         }
     }
 
 
     @Test
     fun testSealed() {
-        assertFailsWithMessages(listOf("p3", "c2")) {
+        assertFailsWithMessages(
+            fields = listOf("p3", "c2"),
+            expectedSerialName = Parent.Child.serializer().descriptor.serialName
+        ) {
             Json.decodeFromString<Parent>("""{"type": "child", "p1":1, "c1": 11}""")
         }
     }
 
     @Test
     fun testTransient() {
-        assertFailsWithMessages(listOf("f3", "f4")) {
+        assertFailsWithMessages(
+            fields = listOf("f3", "f4"),
+            expectedSerialName = WithTransient.serializer().descriptor.serialName
+        ) {
             Json.decodeFromString<WithTransient>("""{"f1":1}""")
         }
     }
 
     @Test
     fun testGeneric() {
-        assertFailsWithMessages(listOf("f2", "f3")) {
+        assertFailsWithMessages(
+            fields = listOf("f2", "f3"),
+            expectedSerialName = Generic.serializer(Int.serializer(), Int.serializer(), Int.serializer()).descriptor.serialName
+        ) {
             Json.decodeFromString<Generic<Int, Int, Int>>("""{"f1":1}""")
         }
     }
 
 
-    private inline fun assertFailsWithMessages(fields: List<String>, block: () -> Any?) {
+    private inline fun assertFailsWithMessages(
+        fields: List<String>,
+        expectedSerialName: String,
+        block: () -> Any?
+    ) {
         val exception = assertFailsWith(MissingFieldException::class, null, block)
         val missedMessages = fields.filter { !exception.message!!.contains(it) }
         assertEquals(exception.missingFields.sorted(), fields.sorted())
+        assertEquals(expectedSerialName, exception.serialName)
         assertTrue(missedMessages.isEmpty(), "Expected message '${exception.message}' to contain substrings $fields")
     }
 }

formats/json/commonMain/src/kotlinx/serialization/json/internal/StreamingJsonDecoder.kt

@@ -92,7 +92,7 @@ internal open class StreamingJsonDecoder(
             // Add "at path" if and only if we've just caught an exception and it hasn't been augmented yet
             if (e.message!!.contains("at path")) throw e
             // NB: we could've use some additional flag marker or augment the stacktrace, but it seemed to be as too much of a burden
-            throw MissingFieldException(e.missingFields, e.message + " at path: " + lexer.path.getPath(), e)
+            throw missingFieldExceptionWithNewMessage(e, e.message + " at path: " + lexer.path.getPath())
         }
     }