feat(client): detect binary incompatible jackson versions (#315)

Author: stainless-app[bot]

orb-java-core/src/main/kotlin/com/withorb/api/core/ObjectMappers.kt

@@ -9,11 +9,15 @@ import com.fasterxml.jackson.databind.SerializationFeature
 import com.fasterxml.jackson.databind.SerializerProvider
 import com.fasterxml.jackson.databind.cfg.CoercionAction.Fail
 import com.fasterxml.jackson.databind.cfg.CoercionInputShape.Integer
+import com.fasterxml.jackson.databind.exc.InvalidDefinitionException
+import com.fasterxml.jackson.databind.exc.UnrecognizedPropertyException
 import com.fasterxml.jackson.databind.json.JsonMapper
 import com.fasterxml.jackson.databind.module.SimpleModule
 import com.fasterxml.jackson.datatype.jdk8.Jdk8Module
 import com.fasterxml.jackson.datatype.jsr310.JavaTimeModule
 import com.fasterxml.jackson.module.kotlin.jacksonMapperBuilder
+import com.withorb.api.errors.OrbException
+import com.withorb.api.errors.OrbInvalidDataException
 import java.io.InputStream
 
 fun jsonMapper(): JsonMapper =
@@ -43,3 +47,38 @@ private object InputStreamJsonSerializer : BaseSerializer<InputStream>(InputStre
         }
     }
 }
+
+@JvmSynthetic
+internal fun enhanceJacksonException(fallbackMessage: String, e: Exception): Exception {
+    // These exceptions should only happen if our code is wrong OR if the user is using a binary
+    // incompatible version of `com.fasterxml.jackson.core:jackson-databind`:
+    // https://javadoc.io/static/com.fasterxml.jackson.core/jackson-databind/2.18.1/index.html
+    val isUnexpectedException =
+        e is UnrecognizedPropertyException || e is InvalidDefinitionException
+    if (!isUnexpectedException) {
+        return OrbInvalidDataException(fallbackMessage, e)
+    }
+
+    val jacksonVersion = JsonMapper::class.java.`package`.implementationVersion
+    if (jacksonVersion.isNullOrEmpty() || jacksonVersion == COMPILED_JACKSON_VERSION) {
+        return OrbInvalidDataException(fallbackMessage, e)
+    }
+
+    return OrbException(
+        """
+            Jackson threw an unexpected exception and its runtime version ($jacksonVersion) mismatches the version the SDK was compiled with ($COMPILED_JACKSON_VERSION).
+
+            You may be using a version of `com.fasterxml.jackson.core:jackson-databind` that's not binary compatible with the SDK.
+
+            This can happen if you are either:
+            1. Directly depending on a different Jackson version
+            2. Depending on some library that depends on a different Jackson version, potentially transitively
+
+            Double-check that you are depending on a compatible Jackson version.
+        """
+            .trimIndent(),
+        e,
+    )
+}
+
+const val COMPILED_JACKSON_VERSION = "2.18.1"

orb-java-core/src/main/kotlin/com/withorb/api/core/handlers/JsonHandler.kt

@@ -4,18 +4,17 @@ package com.withorb.api.core.handlers
 
 import com.fasterxml.jackson.databind.json.JsonMapper
 import com.fasterxml.jackson.module.kotlin.jacksonTypeRef
+import com.withorb.api.core.enhanceJacksonException
 import com.withorb.api.core.http.HttpResponse
 import com.withorb.api.core.http.HttpResponse.Handler
-import com.withorb.api.errors.OrbException
 
 @JvmSynthetic
 internal inline fun <reified T> jsonHandler(jsonMapper: JsonMapper): Handler<T> =
     object : Handler<T> {
-        override fun handle(response: HttpResponse): T {
+        override fun handle(response: HttpResponse): T =
             try {
-                return jsonMapper.readValue(response.body(), jacksonTypeRef())
+                jsonMapper.readValue(response.body(), jacksonTypeRef())
             } catch (e: Exception) {
-                throw OrbException("Error reading response", e)
+                throw enhanceJacksonException("Error reading response", e)
             }
-        }
     }