Allow CopyableThrowable to modify exception message and document message identity in debugging.md

Addresses #1931

Author: qwwdfsad

docs/topics/debugging.md

@@ -63,7 +63,10 @@ Exception copy logic is straightforward:
   1) If the exception class implements [CopyableThrowable], [CopyableThrowable.createCopy] is used.
      `null` can be returned from `createCopy` to opt-out specific exception from being recovered.
   2) If the exception class has class-specific fields not inherited from Throwable, the exception is not copied.
-  3) Otherwise, one of the public exception's constructor is invoked reflectively with an optional `initCause` call.  
+  3) Otherwise, one of the public exception's constructor is invoked reflectively with an optional `initCause` call. 
+  4) If the reflective copy has a changed message (exception constructor passed a modified `message` parameter to the superclass), 
+     the exception is not copied in order to preserve a human-readable message. [CopyableThrowable] does not have such a limitation
+     and allows the copy to have a `message` different from that of the original.
 
 ## Debug agent
 

kotlinx-coroutines-core/common/src/Debug.common.kt

@@ -32,10 +32,15 @@ public interface CopyableThrowable<T> where T : Throwable, T : CopyableThrowable
 
     /**
      * Creates a copy of the current instance.
+     *
      * For better debuggability, it is recommended to use original exception as [cause][Throwable.cause] of the resulting one.
      * Stacktrace of copied exception will be overwritten by stacktrace recovery machinery by [Throwable.setStackTrace] call.
      * An exception can opt-out of copying by returning `null` from this function.
      * Suppressed exceptions of the original exception should not be copied in order to avoid circular exceptions.
+     *
+     * This function is allowed to create a copy with a modified [message][Throwable.message], but it should be noted
+     * that the copy can be later recovered as well and message modification code should handle this situation correctly
+     * (e.g. by also storing the original message and checking it) to produce a human-readable result.
      */
     public fun createCopy(): T?
 }

kotlinx-coroutines-core/jvm/src/internal/StackTraceRecovery.kt

@@ -81,7 +81,8 @@ private fun <E : Throwable> recoverFromStackFrame(exception: E, continuation: Co
 private fun <E : Throwable> tryCopyAndVerify(exception: E): E? {
     val newException = tryCopyException(exception) ?: return null
     // Verify that the new exception has the same message as the original one (bail out if not, see #1631)
-    if (newException.message != exception.message) return null
+    // CopyableThrowable has control over its message and thus can modify it the way it wants
+    if (exception !is CopyableThrowable<*> && newException.message != exception.message) return null
     return newException
 }
 

kotlinx-coroutines-core/jvm/test/exceptions/StackTraceRecoveryCustomExceptionsTest.kt

@@ -89,16 +89,39 @@ class StackTraceRecoveryCustomExceptionsTest : TestBase() {
 
     @Test
     fun testWrongMessageExceptionInChannel() = runTest {
-        // Separate code path
         val result = produce<Unit>(SupervisorJob() + Dispatchers.Unconfined) {
             throw WrongMessageException("OK")
         }
         val ex = runCatching {
+            @Suppress("ControlFlowWithEmptyBody")
             for (unit in result) {
                 // Iterator has a special code path
             }
         }.exceptionOrNull() ?: error("Expected to fail")
         assertTrue(ex is WrongMessageException)
         assertEquals("Token OK", ex.message)
     }
+
+    class CopyableWithCustomMessage(
+        message: String?,
+        cause: Throwable? = null
+    ) : RuntimeException(message, cause),
+        CopyableThrowable<CopyableWithCustomMessage> {
+
+        override fun createCopy(): CopyableWithCustomMessage {
+            return CopyableWithCustomMessage("Recovered: [$message]", cause)
+        }
+    }
+
+    @Test
+    fun testCustomCopyableMessage() = runTest {
+        val result = runCatching {
+            coroutineScope<Unit> {
+                throw CopyableWithCustomMessage("OK")
+            }
+        }
+        val ex = result.exceptionOrNull() ?: error("Expected to fail")
+        assertTrue(ex is CopyableWithCustomMessage)
+        assertEquals("Recovered: [OK]", ex.message)
+    }
 }