impl: add error logging for malformed JSON responses in Coder REST API calls

fioan89 · fioan89 · commit 7d4a8ad00e88 · 2025-08-01T01:18:55.000+03:00
Wraps Moshi converter to log raw response body when JSON parsing fails. It helps debug
malformed JSON during workspace polling by logging full response content, content type, and
error details when a exception during marshalling occurs.

A couple of approaches were tried, unfortunately by the time the exception is raised the
response body has already been consumed by Moshi's converter, so you can't read it again.
The interceptors are also not really a viable option, they are called before the converters which means:

- we don't know if the response body is in the correct form or not. This is problematic
because it means for every rest call we have to read the body twice (interceptor and by
moshi converter)
- we also have to save the intercepted body and store it until we have an exception from
moshi, in which case it will have to be logged.

This approach only logs on conversion failures, and the only performance impact on successful
responses is the fact that we convert the response body byte stream to a string representation
that can later be printed, and then again back to a byte stream by the moshi converter.
diff --git a/src/main/kotlin/com/coder/toolbox/sdk/CoderRestClient.kt b/src/main/kotlin/com/coder/toolbox/sdk/CoderRestClient.kt
@@ -3,6 +3,7 @@ package com.coder.toolbox.sdk
 import com.coder.toolbox.CoderToolboxContext
 import com.coder.toolbox.sdk.convertors.ArchConverter
 import com.coder.toolbox.sdk.convertors.InstantConverter
+import com.coder.toolbox.sdk.convertors.LoggingConverterFactory
 import com.coder.toolbox.sdk.convertors.OSConverter
 import com.coder.toolbox.sdk.convertors.UUIDConverter
 import com.coder.toolbox.sdk.ex.APIResponseException
@@ -133,7 +134,12 @@ open class CoderRestClient(
 
         retroRestClient =
             Retrofit.Builder().baseUrl(url.toString()).client(httpClient)
-                .addConverterFactory(MoshiConverterFactory.create(moshi).asLenient())
+                .addConverterFactory(
+                    LoggingConverterFactory.wrap(
+                        context,
+                        MoshiConverterFactory.create(moshi).asLenient()
+                    )
+                )
                 .build().create(CoderV2RestFacade::class.java)
     }
 
diff --git a/src/main/kotlin/com/coder/toolbox/sdk/convertors/LoggingConverterFactory.kt b/src/main/kotlin/com/coder/toolbox/sdk/convertors/LoggingConverterFactory.kt
@@ -0,0 +1,53 @@
+package com.coder.toolbox.sdk.convertors
+
+import com.coder.toolbox.CoderToolboxContext
+import okhttp3.RequestBody
+import okhttp3.ResponseBody
+import retrofit2.Converter
+import retrofit2.Retrofit
+import java.lang.reflect.Type
+
+class LoggingConverterFactory private constructor(
+    private val context: CoderToolboxContext,
+    private val delegate: Converter.Factory,
+) : Converter.Factory() {
+
+    override fun responseBodyConverter(
+        type: Type,
+        annotations: Array<Annotation>,
+        retrofit: Retrofit
+    ): Converter<ResponseBody, *>? {
+        // Get the delegate converter
+        val delegateConverter = delegate.responseBodyConverter(type, annotations, retrofit)
+            ?: return null
+
+        @Suppress("UNCHECKED_CAST")
+        return LoggingMoshiConverter(context, delegateConverter as Converter<ResponseBody, Any?>)
+    }
+
+    override fun requestBodyConverter(
+        type: Type,
+        parameterAnnotations: Array<Annotation>,
+        methodAnnotations: Array<Annotation>,
+        retrofit: Retrofit
+    ): Converter<*, RequestBody>? {
+        return delegate.requestBodyConverter(type, parameterAnnotations, methodAnnotations, retrofit)
+    }
+
+    override fun stringConverter(
+        type: Type,
+        annotations: Array<Annotation>,
+        retrofit: Retrofit
+    ): Converter<*, String>? {
+        return delegate.stringConverter(type, annotations, retrofit)
+    }
+
+    companion object {
+        fun wrap(
+            context: CoderToolboxContext,
+            delegate: Converter.Factory,
+        ): LoggingConverterFactory {
+            return LoggingConverterFactory(context, delegate)
+        }
+    }
+}
diff --git a/src/main/kotlin/com/coder/toolbox/sdk/convertors/LoggingMoshiConverter.kt b/src/main/kotlin/com/coder/toolbox/sdk/convertors/LoggingMoshiConverter.kt
@@ -0,0 +1,34 @@
+package com.coder.toolbox.sdk.convertors
+
+import com.coder.toolbox.CoderToolboxContext
+import okhttp3.ResponseBody
+import okhttp3.ResponseBody.Companion.toResponseBody
+import retrofit2.Converter
+
+class LoggingMoshiConverter(
+    private val context: CoderToolboxContext,
+    private val delegate: Converter<ResponseBody, Any?>
+) : Converter<ResponseBody, Any> {
+
+    override fun convert(value: ResponseBody): Any? {
+        val bodyString = value.string()
+
+        return try {
+            // Parse with Moshi
+            delegate.convert(bodyString.toResponseBody(value.contentType()))
+        } catch (e: Exception) {
+            // Log the raw content that failed to parse
+            context.logger.error(
+                """
+                |Moshi parsing failed:
+                |Content-Type: ${value.contentType()}
+                |Content: $bodyString
+                |Error: ${e.message}
+            """.trimMargin()
+            )
+
+            // Re-throw so the onFailure callback still gets called
+            throw e
+        }
+    }
+}
