feat(client): make union deserialization more robust (#385)

feat(client): add enum validation method
chore(client): remove unnecessary json state from some query param classes
chore(internal): add json roundtripping tests
chore(internal): add invalid json deserialization tests

Author: stainless-app[bot]

openai-java-core/src/main/kotlin/com/openai/core/BaseDeserializer.kt

@@ -7,11 +7,9 @@ import com.fasterxml.jackson.databind.BeanProperty
 import com.fasterxml.jackson.databind.DeserializationContext
 import com.fasterxml.jackson.databind.JavaType
 import com.fasterxml.jackson.databind.JsonDeserializer
-import com.fasterxml.jackson.databind.JsonMappingException
 import com.fasterxml.jackson.databind.JsonNode
 import com.fasterxml.jackson.databind.deser.ContextualDeserializer
 import com.fasterxml.jackson.databind.deser.std.StdDeserializer
-import com.openai.errors.OpenAIInvalidDataException
 import kotlin.reflect.KClass
 
 abstract class BaseDeserializer<T : Any>(type: KClass<T>) :
@@ -30,38 +28,17 @@ abstract class BaseDeserializer<T : Any>(type: KClass<T>) :
 
     protected abstract fun ObjectCodec.deserialize(node: JsonNode): T
 
-    protected fun <T> ObjectCodec.deserialize(node: JsonNode, type: TypeReference<T>): T =
+    protected fun <T> ObjectCodec.tryDeserialize(node: JsonNode, type: TypeReference<T>): T? =
         try {
             readValue(treeAsTokens(node), type)
         } catch (e: Exception) {
-            throw OpenAIInvalidDataException("Error deserializing", e)
-        }
-
-    protected fun <T> ObjectCodec.tryDeserialize(
-        node: JsonNode,
-        type: TypeReference<T>,
-        validate: (T) -> Unit = {},
-    ): T? {
-        return try {
-            readValue(treeAsTokens(node), type).apply(validate)
-        } catch (e: JsonMappingException) {
-            null
-        } catch (e: RuntimeException) {
             null
         }
-    }
 
-    protected fun <T> ObjectCodec.tryDeserialize(
-        node: JsonNode,
-        type: JavaType,
-        validate: (T) -> Unit = {},
-    ): T? {
-        return try {
-            readValue<T>(treeAsTokens(node), type).apply(validate)
-        } catch (e: JsonMappingException) {
-            null
-        } catch (e: RuntimeException) {
+    protected fun <T> ObjectCodec.tryDeserialize(node: JsonNode, type: JavaType): T? =
+        try {
+            readValue(treeAsTokens(node), type)
+        } catch (e: Exception) {
             null
         }
-    }
 }

openai-java-core/src/main/kotlin/com/openai/core/Utils.kt

@@ -25,6 +25,34 @@ internal fun <K : Comparable<K>, V> SortedMap<K, V>.toImmutable(): SortedMap<K,
     if (isEmpty()) Collections.emptySortedMap()
     else Collections.unmodifiableSortedMap(toSortedMap(comparator()))
 
+/**
+ * Returns all elements that yield the largest value for the given function, or an empty list if
+ * there are zero elements.
+ *
+ * This is similar to [Sequence.maxByOrNull] except it returns _all_ elements that yield the largest
+ * value; not just the first one.
+ */
+@JvmSynthetic
+internal fun <T, R : Comparable<R>> Sequence<T>.allMaxBy(selector: (T) -> R): List<T> {
+    var maxValue: R? = null
+    val maxElements = mutableListOf<T>()
+
+    val iterator = iterator()
+    while (iterator.hasNext()) {
+        val element = iterator.next()
+        val value = selector(element)
+        if (maxValue == null || value > maxValue) {
+            maxValue = value
+            maxElements.clear()
+            maxElements.add(element)
+        } else if (value == maxValue) {
+            maxElements.add(element)
+        }
+    }
+
+    return maxElements
+}
+
 /**
  * Returns whether [this] is equal to [other].
  *

openai-java-core/src/main/kotlin/com/openai/models/AllModels.kt

@@ -15,6 +15,7 @@ import com.openai.core.BaseSerializer
 import com.openai.core.Enum
 import com.openai.core.JsonField
 import com.openai.core.JsonValue
+import com.openai.core.allMaxBy
 import com.openai.core.getOrThrow
 import com.openai.errors.OpenAIInvalidDataException
 import java.util.Objects
@@ -50,14 +51,13 @@ private constructor(
 
     fun _json(): Optional<JsonValue> = Optional.ofNullable(_json)
 
-    fun <T> accept(visitor: Visitor<T>): T {
-        return when {
+    fun <T> accept(visitor: Visitor<T>): T =
+        when {
             string != null -> visitor.visitString(string)
             chatModel != null -> visitor.visitChatModel(chatModel)
             unionMember2 != null -> visitor.visitUnionMember2(unionMember2)
             else -> visitor.unknown(_json)
         }
-    }
 
     private var validated: Boolean = false
 
@@ -70,14 +70,45 @@ private constructor(
             object : Visitor<Unit> {
                 override fun visitString(string: String) {}
 
-                override fun visitChatModel(chatModel: ChatModel) {}
+                override fun visitChatModel(chatModel: ChatModel) {
+                    chatModel.validate()
+                }
 
-                override fun visitUnionMember2(unionMember2: UnionMember2) {}
+                override fun visitUnionMember2(unionMember2: UnionMember2) {
+                    unionMember2.validate()
+                }
             }
         )
         validated = true
     }
 
+    fun isValid(): Boolean =
+        try {
+            validate()
+            true
+        } catch (e: OpenAIInvalidDataException) {
+            false
+        }
+
+    /**
+     * Returns a score indicating how many valid values are contained in this object recursively.
+     *
+     * Used for best match union deserialization.
+     */
+    @JvmSynthetic
+    internal fun validity(): Int =
+        accept(
+            object : Visitor<Int> {
+                override fun visitString(string: String) = 1
+
+                override fun visitChatModel(chatModel: ChatModel) = chatModel.validity()
+
+                override fun visitUnionMember2(unionMember2: UnionMember2) = unionMember2.validity()
+
+                override fun unknown(json: JsonValue?) = 0
+            }
+        )
+
     override fun equals(other: Any?): Boolean {
         if (this === other) {
             return true
@@ -135,17 +166,30 @@ private constructor(
         override fun ObjectCodec.deserialize(node: JsonNode): AllModels {
             val json = JsonValue.fromJsonNode(node)
 
-            tryDeserialize(node, jacksonTypeRef<String>())?.let {
-                return AllModels(string = it, _json = json)
-            }
-            tryDeserialize(node, jacksonTypeRef<ChatModel>())?.let {
-                return AllModels(chatModel = it, _json = json)
-            }
-            tryDeserialize(node, jacksonTypeRef<UnionMember2>())?.let {
-                return AllModels(unionMember2 = it, _json = json)
+            val bestMatches =
+                sequenceOf(
+                        tryDeserialize(node, jacksonTypeRef<ChatModel>())?.let {
+                            AllModels(chatModel = it, _json = json)
+                        },
+                        tryDeserialize(node, jacksonTypeRef<UnionMember2>())?.let {
+                            AllModels(unionMember2 = it, _json = json)
+                        },
+                        tryDeserialize(node, jacksonTypeRef<String>())?.let {
+                            AllModels(string = it, _json = json)
+                        },
+                    )
+                    .filterNotNull()
+                    .allMaxBy { it.validity() }
+                    .toList()
+            return when (bestMatches.size) {
+                // This can happen if what we're deserializing is completely incompatible with all
+                // the possible variants (e.g. deserializing from object).
+                0 -> AllModels(_json = json)
+                1 -> bestMatches.single()
+                // If there's more than one match with the highest validity, then use the first
+                // completely valid match, or simply the first match if none are completely valid.
+                else -> bestMatches.firstOrNull { it.isValid() } ?: bestMatches.first()
             }
-
-            return AllModels(_json = json)
         }
     }
 
@@ -266,6 +310,33 @@ private constructor(
         fun asString(): String =
             _value().asString().orElseThrow { OpenAIInvalidDataException("Value is not a String") }
 
+        private var validated: Boolean = false
+
+        fun validate(): UnionMember2 = apply {
+            if (validated) {
+                return@apply
+            }
+
+            known()
+            validated = true
+        }
+
+        fun isValid(): Boolean =
+            try {
+                validate()
+                true
+            } catch (e: OpenAIInvalidDataException) {
+                false
+            }
+
+        /**
+         * Returns a score indicating how many valid values are contained in this object
+         * recursively.
+         *
+         * Used for best match union deserialization.
+         */
+        @JvmSynthetic internal fun validity(): Int = if (value() == Value._UNKNOWN) 0 else 1
+
         override fun equals(other: Any?): Boolean {
             if (this === other) {
                 return true

openai-java-core/src/main/kotlin/com/openai/models/ChatModel.kt

@@ -338,6 +338,32 @@ class ChatModel @JsonCreator private constructor(private val value: JsonField<St
     fun asString(): String =
         _value().asString().orElseThrow { OpenAIInvalidDataException("Value is not a String") }
 
+    private var validated: Boolean = false
+
+    fun validate(): ChatModel = apply {
+        if (validated) {
+            return@apply
+        }
+
+        known()
+        validated = true
+    }
+
+    fun isValid(): Boolean =
+        try {
+            validate()
+            true
+        } catch (e: OpenAIInvalidDataException) {
+            false
+        }
+
+    /**
+     * Returns a score indicating how many valid values are contained in this object recursively.
+     *
+     * Used for best match union deserialization.
+     */
+    @JvmSynthetic internal fun validity(): Int = if (value() == Value._UNKNOWN) 0 else 1
+
     override fun equals(other: Any?): Boolean {
         if (this === other) {
             return true