Better exception handling in StdioClientTransport (#444)
# Better exception handling in StdioClientTransport Refactor `McpException` for improved handling with convenience constructors and enhanced exception wrapping logic in `StdioClientTransport`. Update tests to use `kotest` matchers and add JUnit parameterized tests for exception handling. ## Motivation and Context #442 follow up ## How Has This Been Tested? <!-- Have you tested this in a real application? Which scenarios were tested? --> ## Breaking Changes <!-- Will users need to update their code or configurations? --> ## Types of changes <!-- What types of changes does your code introduce? Put an `x` in all the boxes that apply: --> - [x] Bug fix (non-breaking change which fixes an issue) - [ ] New feature (non-breaking change which adds functionality) - [ ] Breaking change (fix or feature that would cause existing functionality to change) - [ ] Documentation update ## Checklist <!-- Go over all the following points, and put an `x` in all the boxes that apply. --> - [ ] I have read the [MCP Documentation](https://modelcontextprotocol.io) - [ ] My code follows the repository's style guidelines - [ ] New and existing tests pass locally - [ ] I have added appropriate error handling - [ ] I have added or updated documentation as needed ## Additional context <!-- Add any other context, implementation notes, or design decisions -->
This commit is contained in:
parent
bb8de718d9
commit
6ec6d3c52f
7 changed files with 121 additions and 15 deletions
|
|
@ -22,6 +22,7 @@ mockk = "1.14.6"
|
||||||
mokksy = "0.6.2"
|
mokksy = "0.6.2"
|
||||||
serialization = "1.9.0"
|
serialization = "1.9.0"
|
||||||
slf4j = "2.0.17"
|
slf4j = "2.0.17"
|
||||||
|
junit="6.0.1"
|
||||||
|
|
||||||
[libraries]
|
[libraries]
|
||||||
# Plugins
|
# Plugins
|
||||||
|
|
@ -58,6 +59,7 @@ mockk = { module = "io.mockk:mockk", version.ref = "mockk" }
|
||||||
mokksy = { group = "dev.mokksy", name = "mokksy", version.ref = "mokksy" }
|
mokksy = { group = "dev.mokksy", name = "mokksy", version.ref = "mokksy" }
|
||||||
netty-bom = { group = "io.netty", name = "netty-bom", version.ref = "netty" }
|
netty-bom = { group = "io.netty", name = "netty-bom", version.ref = "netty" }
|
||||||
slf4j-simple = { group = "org.slf4j", name = "slf4j-simple", version.ref = "slf4j" }
|
slf4j-simple = { group = "org.slf4j", name = "slf4j-simple", version.ref = "slf4j" }
|
||||||
|
junit-jupiter-params = { module = "org.junit.jupiter:junit-jupiter-params", version.ref = "junit" }
|
||||||
|
|
||||||
# Samples
|
# Samples
|
||||||
ktor-client-cio = { group = "io.ktor", name = "ktor-client-cio", version.ref = "ktor" }
|
ktor-client-cio = { group = "io.ktor", name = "ktor-client-cio", version.ref = "ktor" }
|
||||||
|
|
|
||||||
|
|
@ -54,6 +54,7 @@ kotlin {
|
||||||
implementation(libs.awaitility)
|
implementation(libs.awaitility)
|
||||||
implementation(libs.ktor.client.apache5)
|
implementation(libs.ktor.client.apache5)
|
||||||
implementation(libs.mockk)
|
implementation(libs.mockk)
|
||||||
|
implementation(libs.junit.jupiter.params)
|
||||||
implementation(libs.mokksy)
|
implementation(libs.mokksy)
|
||||||
implementation(dependencies.platform(libs.netty.bom))
|
implementation(dependencies.platform(libs.netty.bom))
|
||||||
runtimeOnly(libs.slf4j.simple)
|
runtimeOnly(libs.slf4j.simple)
|
||||||
|
|
|
||||||
|
|
@ -15,6 +15,7 @@ import io.modelcontextprotocol.kotlin.sdk.types.JSONRPCMessage
|
||||||
import io.modelcontextprotocol.kotlin.sdk.types.McpException
|
import io.modelcontextprotocol.kotlin.sdk.types.McpException
|
||||||
import io.modelcontextprotocol.kotlin.sdk.types.RPCError.ErrorCode.CONNECTION_CLOSED
|
import io.modelcontextprotocol.kotlin.sdk.types.RPCError.ErrorCode.CONNECTION_CLOSED
|
||||||
import io.modelcontextprotocol.kotlin.sdk.types.RPCError.ErrorCode.INTERNAL_ERROR
|
import io.modelcontextprotocol.kotlin.sdk.types.RPCError.ErrorCode.INTERNAL_ERROR
|
||||||
|
import kotlinx.coroutines.CancellationException
|
||||||
import kotlinx.coroutines.CoroutineName
|
import kotlinx.coroutines.CoroutineName
|
||||||
import kotlinx.coroutines.CoroutineScope
|
import kotlinx.coroutines.CoroutineScope
|
||||||
import kotlinx.coroutines.Dispatchers
|
import kotlinx.coroutines.Dispatchers
|
||||||
|
|
@ -71,12 +72,14 @@ import kotlin.jvm.JvmOverloads
|
||||||
* @param input The input stream where messages are received.
|
* @param input The input stream where messages are received.
|
||||||
* @param output The output stream where messages are sent.
|
* @param output The output stream where messages are sent.
|
||||||
* @param error Optional error stream for stderr monitoring.
|
* @param error Optional error stream for stderr monitoring.
|
||||||
* @param sendChannel Channel for outbound messages. Default: buffered channel (capacity 64).
|
* @param sendChannel Channel for outbound messages. Default: buffered channel
|
||||||
|
* (<a jref="https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.channels/-channel/-factory/-b-u-f-f-e-r-e-d.html">implementation-default capacity</a>).
|
||||||
* @param classifyStderr Callback to classify stderr lines. Return [StderrSeverity.FATAL] to fail transport,
|
* @param classifyStderr Callback to classify stderr lines. Return [StderrSeverity.FATAL] to fail transport,
|
||||||
* or [StderrSeverity.WARNING] / [StderrSeverity.INFO] / [StderrSeverity.DEBUG]
|
* or [StderrSeverity.WARNING] / [StderrSeverity.INFO] / [StderrSeverity.DEBUG]
|
||||||
* to log, or [StderrSeverity.IGNORE] to discard.
|
* to log, or [StderrSeverity.IGNORE] to discard.
|
||||||
* Default value: [StderrSeverity.DEBUG].
|
* Default value: [StderrSeverity.DEBUG].
|
||||||
* @see <a href="https://modelcontextprotocol.io/specification/2025-11-25/basic/transports#stdio">MCP Specification</a>
|
* @see <a href="https://modelcontextprotocol.io/specification/2025-06-18/basic/transports#stdio">MCP Specification</a>
|
||||||
|
* @see [Channel.BUFFERED]
|
||||||
*/
|
*/
|
||||||
@OptIn(ExperimentalAtomicApi::class)
|
@OptIn(ExperimentalAtomicApi::class)
|
||||||
public class StdioClientTransport @JvmOverloads public constructor(
|
public class StdioClientTransport @JvmOverloads public constructor(
|
||||||
|
|
@ -232,15 +235,25 @@ public class StdioClientTransport @JvmOverloads public constructor(
|
||||||
@Suppress("TooGenericExceptionCaught", "SwallowedException")
|
@Suppress("TooGenericExceptionCaught", "SwallowedException")
|
||||||
try {
|
try {
|
||||||
sendChannel.send(message)
|
sendChannel.send(message)
|
||||||
|
} catch (e: CancellationException) {
|
||||||
|
throw e // MUST rethrow immediately - don't log, don't wrap
|
||||||
} catch (e: ClosedSendChannelException) {
|
} catch (e: ClosedSendChannelException) {
|
||||||
logger.debug(e) { "Cannot send message: transport is closed" }
|
logger.debug(e) { "Cannot send message: transport is closed" }
|
||||||
throw McpException(CONNECTION_CLOSED, "Transport is closed")
|
throw McpException(
|
||||||
|
code = CONNECTION_CLOSED,
|
||||||
|
message = "Transport is closed",
|
||||||
|
cause = e,
|
||||||
|
)
|
||||||
} catch (e: McpException) {
|
} catch (e: McpException) {
|
||||||
logger.debug(e) { "Error while sending message: ${e.message}" }
|
logger.debug(e) { "Error while sending message: ${e.message}" }
|
||||||
throw e
|
throw e
|
||||||
} catch (e: Exception) {
|
} catch (e: Throwable) {
|
||||||
logger.error(e) { "Error while sending message: ${e.message}" }
|
logger.error(e) { "Error while sending message: ${e.message}" }
|
||||||
throw McpException(INTERNAL_ERROR, "Error while sending message: ${e.message}")
|
throw McpException(
|
||||||
|
code = INTERNAL_ERROR,
|
||||||
|
message = "Error while sending message: ${e.message}",
|
||||||
|
cause = e,
|
||||||
|
)
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -1,12 +1,28 @@
|
||||||
package io.modelcontextprotocol.kotlin.sdk.client.stdio
|
package io.modelcontextprotocol.kotlin.sdk.client.stdio
|
||||||
|
|
||||||
|
import io.kotest.assertions.throwables.shouldThrow
|
||||||
import io.kotest.matchers.booleans.shouldBeFalse
|
import io.kotest.matchers.booleans.shouldBeFalse
|
||||||
import io.kotest.matchers.shouldBe
|
import io.kotest.matchers.shouldBe
|
||||||
|
import io.kotest.matchers.types.shouldBeInstanceOf
|
||||||
|
import io.kotest.matchers.types.shouldBeSameInstanceAs
|
||||||
|
import io.mockk.coEvery
|
||||||
|
import io.mockk.mockk
|
||||||
import io.modelcontextprotocol.kotlin.sdk.client.StdioClientTransport
|
import io.modelcontextprotocol.kotlin.sdk.client.StdioClientTransport
|
||||||
|
import io.modelcontextprotocol.kotlin.sdk.types.JSONRPCMessage
|
||||||
|
import io.modelcontextprotocol.kotlin.sdk.types.JSONRPCRequest
|
||||||
|
import io.modelcontextprotocol.kotlin.sdk.types.McpException
|
||||||
|
import io.modelcontextprotocol.kotlin.sdk.types.RPCError.ErrorCode
|
||||||
|
import kotlinx.coroutines.CancellationException
|
||||||
|
import kotlinx.coroutines.channels.Channel
|
||||||
|
import kotlinx.coroutines.channels.ClosedSendChannelException
|
||||||
import kotlinx.coroutines.delay
|
import kotlinx.coroutines.delay
|
||||||
import kotlinx.coroutines.test.runTest
|
import kotlinx.coroutines.test.runTest
|
||||||
import kotlinx.io.Buffer
|
import kotlinx.io.Buffer
|
||||||
import kotlinx.io.writeString
|
import kotlinx.io.writeString
|
||||||
|
import org.junit.jupiter.params.ParameterizedTest
|
||||||
|
import org.junit.jupiter.params.provider.Arguments
|
||||||
|
import org.junit.jupiter.params.provider.MethodSource
|
||||||
|
import java.util.stream.Stream
|
||||||
import kotlin.concurrent.atomics.AtomicBoolean
|
import kotlin.concurrent.atomics.AtomicBoolean
|
||||||
import kotlin.concurrent.atomics.ExperimentalAtomicApi
|
import kotlin.concurrent.atomics.ExperimentalAtomicApi
|
||||||
import kotlin.test.Test
|
import kotlin.test.Test
|
||||||
|
|
@ -95,4 +111,66 @@ class StdioClientTransportErrorHandlingTest {
|
||||||
// Empty input should close cleanly without error
|
// Empty input should close cleanly without error
|
||||||
errorCalled.shouldBeFalse()
|
errorCalled.shouldBeFalse()
|
||||||
}
|
}
|
||||||
|
|
||||||
|
companion object {
|
||||||
|
@JvmStatic
|
||||||
|
fun exceptions(): Stream<Arguments> = Stream.of(
|
||||||
|
Arguments.of(
|
||||||
|
CancellationException(),
|
||||||
|
false, // should not wrap, propagate
|
||||||
|
null,
|
||||||
|
),
|
||||||
|
Arguments.of(
|
||||||
|
McpException(-1, "dummy"),
|
||||||
|
false, // should not wrap, propagate
|
||||||
|
null,
|
||||||
|
),
|
||||||
|
Arguments.of(
|
||||||
|
ClosedSendChannelException("dummy"),
|
||||||
|
true, // should wrap in McpException
|
||||||
|
ErrorCode.CONNECTION_CLOSED,
|
||||||
|
),
|
||||||
|
Arguments.of(
|
||||||
|
Exception(),
|
||||||
|
true,
|
||||||
|
ErrorCode.INTERNAL_ERROR,
|
||||||
|
),
|
||||||
|
Arguments.of(
|
||||||
|
OutOfMemoryError(),
|
||||||
|
true,
|
||||||
|
ErrorCode.INTERNAL_ERROR,
|
||||||
|
),
|
||||||
|
|
||||||
|
)
|
||||||
|
}
|
||||||
|
|
||||||
|
@ParameterizedTest
|
||||||
|
@MethodSource("exceptions")
|
||||||
|
fun `Send should handle exceptions`(throwable: Throwable, shouldWrap: Boolean, expectedCode: Int?) = runTest {
|
||||||
|
val sendChannel: Channel<JSONRPCMessage> = mockk(relaxed = true)
|
||||||
|
|
||||||
|
transport = StdioClientTransport(
|
||||||
|
input = Buffer(),
|
||||||
|
output = Buffer(),
|
||||||
|
sendChannel = sendChannel,
|
||||||
|
)
|
||||||
|
|
||||||
|
coEvery { sendChannel.send(any()) } throws throwable
|
||||||
|
|
||||||
|
transport.start()
|
||||||
|
|
||||||
|
// Cancel the coroutine while it's suspended in send()
|
||||||
|
val exception = shouldThrow<Throwable> {
|
||||||
|
transport.send(JSONRPCRequest(id = "test-1", method = "test/method"))
|
||||||
|
}
|
||||||
|
|
||||||
|
if (shouldWrap) {
|
||||||
|
exception.shouldBeInstanceOf<McpException> {
|
||||||
|
it.cause shouldBeSameInstanceAs throwable
|
||||||
|
it.code shouldBe expectedCode
|
||||||
|
}
|
||||||
|
} else {
|
||||||
|
exception shouldBeSameInstanceAs throwable
|
||||||
|
}
|
||||||
|
}
|
||||||
}
|
}
|
||||||
|
|
|
||||||
|
|
@ -2654,11 +2654,12 @@ public abstract interface annotation class io/modelcontextprotocol/kotlin/sdk/ty
|
||||||
}
|
}
|
||||||
|
|
||||||
public final class io/modelcontextprotocol/kotlin/sdk/types/McpException : java/lang/Exception {
|
public final class io/modelcontextprotocol/kotlin/sdk/types/McpException : java/lang/Exception {
|
||||||
|
public fun <init> (ILjava/lang/String;)V
|
||||||
public fun <init> (ILjava/lang/String;Lkotlinx/serialization/json/JsonElement;)V
|
public fun <init> (ILjava/lang/String;Lkotlinx/serialization/json/JsonElement;)V
|
||||||
public synthetic fun <init> (ILjava/lang/String;Lkotlinx/serialization/json/JsonElement;ILkotlin/jvm/internal/DefaultConstructorMarker;)V
|
public fun <init> (ILjava/lang/String;Lkotlinx/serialization/json/JsonElement;Ljava/lang/Throwable;)V
|
||||||
|
public synthetic fun <init> (ILjava/lang/String;Lkotlinx/serialization/json/JsonElement;Ljava/lang/Throwable;ILkotlin/jvm/internal/DefaultConstructorMarker;)V
|
||||||
public final fun getCode ()I
|
public final fun getCode ()I
|
||||||
public final fun getData ()Lkotlinx/serialization/json/JsonElement;
|
public final fun getData ()Lkotlinx/serialization/json/JsonElement;
|
||||||
public fun getMessage ()Ljava/lang/String;
|
|
||||||
}
|
}
|
||||||
|
|
||||||
public abstract interface class io/modelcontextprotocol/kotlin/sdk/types/MediaContent : io/modelcontextprotocol/kotlin/sdk/types/ContentBlock {
|
public abstract interface class io/modelcontextprotocol/kotlin/sdk/types/MediaContent : io/modelcontextprotocol/kotlin/sdk/types/ContentBlock {
|
||||||
|
|
|
||||||
|
|
@ -1,14 +1,19 @@
|
||||||
package io.modelcontextprotocol.kotlin.sdk.types
|
package io.modelcontextprotocol.kotlin.sdk.types
|
||||||
|
|
||||||
import kotlinx.serialization.json.JsonElement
|
import kotlinx.serialization.json.JsonElement
|
||||||
|
import kotlin.jvm.JvmOverloads
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* Represents an error specific to the MCP protocol.
|
* Represents an error specific to the MCP protocol.
|
||||||
*
|
*
|
||||||
* @property code The error code.
|
* @property code The MCP/JSON‑RPC error code.
|
||||||
* @property message The error message.
|
* @property data Optional additional error payload as a JSON element; `null` when not provided.
|
||||||
* @property data Additional error data as a JSON object.
|
* @param message The error message.
|
||||||
|
* @param cause The original cause.
|
||||||
*/
|
*/
|
||||||
public class McpException(public val code: Int, message: String, public val data: JsonElement? = null) : Exception() {
|
public class McpException @JvmOverloads public constructor(
|
||||||
override val message: String = "MCP error $code: $message"
|
public val code: Int,
|
||||||
}
|
message: String,
|
||||||
|
public val data: JsonElement? = null,
|
||||||
|
cause: Throwable? = null,
|
||||||
|
) : Exception("MCP error $code: $message", cause)
|
||||||
|
|
|
||||||
|
|
@ -1,5 +1,7 @@
|
||||||
package io.modelcontextprotocol.kotlin.sdk.integration.kotlin
|
package io.modelcontextprotocol.kotlin.sdk.integration.kotlin
|
||||||
|
|
||||||
|
import io.kotest.assertions.withClue
|
||||||
|
import io.kotest.matchers.string.shouldContain
|
||||||
import io.modelcontextprotocol.kotlin.sdk.types.GetPromptRequest
|
import io.modelcontextprotocol.kotlin.sdk.types.GetPromptRequest
|
||||||
import io.modelcontextprotocol.kotlin.sdk.types.GetPromptRequestParams
|
import io.modelcontextprotocol.kotlin.sdk.types.GetPromptRequestParams
|
||||||
import io.modelcontextprotocol.kotlin.sdk.types.GetPromptResult
|
import io.modelcontextprotocol.kotlin.sdk.types.GetPromptResult
|
||||||
|
|
@ -391,7 +393,9 @@ abstract class AbstractPromptIntegrationTest : KotlinTestBase() {
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|
||||||
assertTrue(exception.message.contains("requiredArg2"), "Exception should mention the missing argument")
|
withClue("Exception should mention the missing argument") {
|
||||||
|
exception.message shouldContain "requiredArg2"
|
||||||
|
}
|
||||||
|
|
||||||
// test with no args
|
// test with no args
|
||||||
val exception2 = assertThrows<McpException> {
|
val exception2 = assertThrows<McpException> {
|
||||||
|
|
@ -407,7 +411,9 @@ abstract class AbstractPromptIntegrationTest : KotlinTestBase() {
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|
||||||
assertTrue(exception2.message.contains("requiredArg"), "Exception should mention a missing required argument")
|
withClue("Exception should mention a missing required argument") {
|
||||||
|
exception2.message shouldContain "requiredArg"
|
||||||
|
}
|
||||||
|
|
||||||
// test with all required args
|
// test with all required args
|
||||||
val result = client.getPrompt(
|
val result = client.getPrompt(
|
||||||
|
|
|
||||||
Loading…
Reference in a new issue