## refactor: Introduce AbstractClientTransport and simplify client transport lifecycle This PR unifies state management logic across client transports, except for the websocket transport, as it needs more refactoring first and is not the primary transport. - Introduce `AbstractClientTransport` as base class for other client transports. - Migrate to `ClientTransportState` states with state machine, streamline state management. - Ensure proper cleanup and error handling consistency across transport implementations. - Add unit tests to validate `AbstractClientTransport` behavior and state transitions. - Update related documentation and API contract. - Make sure `onClose` callback is called at most once - fix [StreamableHttpClientTransportTest.kt](https://github.com/modelcontextprotocol/kotlin-sdk/pull/516/changes#diff-b9fe8891d08a492448a7ed2dc782151c6a915ae1403a4d70c2034c6062c84cb5) to throw `McpException` on connect when received invalid Json ## Motivation and Context Unify lifecycle handling and eliminate duplication in client Transport implementations. ## How Has This Been Tested? Unit test, regression tests ## Breaking Changes - `onClose` callback is now called only once - send(...) will throw McpException with message "Transport is not ready" when `ClientTransportState != Operational` ## Types of changes - [ ] Bug fix (non-breaking change which fixes an issue) - [x] Refactoring - [ ] New feature (non-breaking change which adds functionality) - [x] 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. --> - [x] I have read the [MCP Documentation](https://modelcontextprotocol.io) - [x] 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 See #517
This commit is contained in:
parent
99908beb2a
commit
6120b3109e
1 changed files with 1057 additions and 191 deletions
|
|
@ -0,0 +1,498 @@
|
|||
package io.modelcontextprotocol.kotlin.sdk.shared
|
||||
|
||||
import io.github.oshai.kotlinlogging.KLogger
|
||||
import io.github.oshai.kotlinlogging.KotlinLogging
|
||||
import io.kotest.assertions.throwables.shouldThrow
|
||||
import io.kotest.matchers.shouldBe
|
||||
import io.kotest.matchers.string.shouldContain
|
||||
import io.mockk.spyk
|
||||
import io.modelcontextprotocol.kotlin.sdk.InternalMcpApi
|
||||
import io.modelcontextprotocol.kotlin.sdk.types.JSONRPCMessage
|
||||
import io.modelcontextprotocol.kotlin.sdk.types.McpException
|
||||
import io.modelcontextprotocol.kotlin.sdk.types.PingRequest
|
||||
import io.modelcontextprotocol.kotlin.sdk.types.RPCError
|
||||
import io.modelcontextprotocol.kotlin.sdk.types.toJSON
|
||||
import kotlinx.coroutines.test.runTest
|
||||
import org.junit.jupiter.api.BeforeEach
|
||||
import org.junit.jupiter.api.DisplayName
|
||||
import org.junit.jupiter.api.Nested
|
||||
import org.junit.jupiter.api.Test
|
||||
import org.junit.jupiter.params.ParameterizedTest
|
||||
import org.junit.jupiter.params.provider.CsvSource
|
||||
import org.junit.jupiter.params.provider.EnumSource
|
||||
import org.junit.jupiter.params.provider.MethodSource
|
||||
import kotlin.concurrent.atomics.ExperimentalAtomicApi
|
||||
import kotlin.coroutines.cancellation.CancellationException
|
||||
|
||||
/**
|
||||
* Unit tests for [AbstractClientTransport] state machine and lifecycle.
|
||||
*
|
||||
* Tests behavioral correctness of state transitions, lifecycle management,
|
||||
* and message sending without relying on mocking frameworks.
|
||||
*/
|
||||
@OptIn(ExperimentalAtomicApi::class)
|
||||
class AbstractClientTransportTest {
|
||||
|
||||
companion object {
|
||||
@JvmStatic
|
||||
fun nonMcpExceptions() = listOf(
|
||||
TestException("Generic failure"),
|
||||
java.io.IOException("Network error"),
|
||||
IllegalStateException("Invalid state"),
|
||||
)
|
||||
}
|
||||
|
||||
private lateinit var transport: TestClientTransport
|
||||
|
||||
@BeforeEach
|
||||
fun beforeEach() {
|
||||
transport = spyk(TestClientTransport())
|
||||
}
|
||||
|
||||
@Nested
|
||||
@DisplayName("Lifecycle")
|
||||
inner class LifecycleTests {
|
||||
|
||||
@Test
|
||||
fun `should start with NEW state`() {
|
||||
transport.currentState shouldBe ClientTransportState.New
|
||||
}
|
||||
|
||||
@Test
|
||||
fun `should transition to OPERATIONAL after successful start`() = runTest {
|
||||
transport.start()
|
||||
|
||||
transport.currentState shouldBe ClientTransportState.Operational
|
||||
transport.initializeCalled shouldBe true
|
||||
}
|
||||
|
||||
@Test
|
||||
fun `should call initialize during start`() = runTest {
|
||||
transport.start()
|
||||
|
||||
transport.initializeCalled shouldBe true
|
||||
transport.currentState shouldBe ClientTransportState.Operational
|
||||
}
|
||||
|
||||
@Test
|
||||
fun `should transition to INITIALIZATION_FAILED on start error`() = runTest {
|
||||
transport.shouldFailInitialization = true
|
||||
|
||||
shouldThrow<TestException> {
|
||||
transport.start()
|
||||
}
|
||||
|
||||
transport.currentState shouldBe ClientTransportState.InitializationFailed
|
||||
transport.closeResourcesCalled shouldBe true
|
||||
}
|
||||
|
||||
@Test
|
||||
fun `should call closeResources on initialization failure`() = runTest {
|
||||
transport.shouldFailInitialization = true
|
||||
|
||||
shouldThrow<TestException> {
|
||||
transport.start()
|
||||
}
|
||||
|
||||
transport.closeResourcesCalled shouldBe true
|
||||
}
|
||||
|
||||
@Test
|
||||
fun `should reject starting twice`() = runTest {
|
||||
transport.start()
|
||||
|
||||
val exception = shouldThrow<IllegalStateException> {
|
||||
transport.start()
|
||||
}
|
||||
exception.message shouldContain "expected transport state New"
|
||||
}
|
||||
|
||||
@Test
|
||||
fun `should transition to STOPPED after successful close`() = runTest {
|
||||
transport.start()
|
||||
transport.close()
|
||||
|
||||
transport.currentState shouldBe ClientTransportState.Stopped
|
||||
transport.closeResourcesCalled shouldBe true
|
||||
}
|
||||
|
||||
@Test
|
||||
fun `should call closeResources during close`() = runTest {
|
||||
transport.start()
|
||||
|
||||
transport.close()
|
||||
|
||||
transport.closeResourcesCalled shouldBe true
|
||||
transport.currentState shouldBe ClientTransportState.Stopped
|
||||
}
|
||||
|
||||
@Test
|
||||
fun `should be idempotent when closed multiple times`() = runTest {
|
||||
// given
|
||||
transport.start()
|
||||
transport.close()
|
||||
// when
|
||||
transport.close()
|
||||
transport.close()
|
||||
|
||||
transport.currentState shouldBe ClientTransportState.Stopped
|
||||
transport.closeResourcesCallCount shouldBe 1
|
||||
}
|
||||
|
||||
@Test
|
||||
fun `should call onClose callback exactly once on multiple close calls`() = runTest {
|
||||
var onCloseCallCount = 0
|
||||
transport.onClose { onCloseCallCount++ }
|
||||
|
||||
transport.start()
|
||||
transport.close()
|
||||
transport.close()
|
||||
|
||||
onCloseCallCount shouldBe 1
|
||||
}
|
||||
|
||||
@Test
|
||||
fun `should transition to SHUTDOWN_FAILED on close error`() = runTest {
|
||||
transport.shouldFailClose = true
|
||||
transport.start()
|
||||
|
||||
transport.close()
|
||||
|
||||
transport.currentState shouldBe ClientTransportState.ShutdownFailed
|
||||
}
|
||||
|
||||
@Test
|
||||
fun `should call onClose even when close fails`() = runTest {
|
||||
// given
|
||||
var onCloseCalled = false
|
||||
transport.onClose { onCloseCalled = true }
|
||||
transport.shouldFailClose = true
|
||||
transport.start()
|
||||
// when
|
||||
transport.close()
|
||||
// then
|
||||
onCloseCalled shouldBe true
|
||||
}
|
||||
|
||||
@Test
|
||||
fun `should propagate CancellationException on close`() = runTest {
|
||||
// given
|
||||
transport.shouldThrowCancellation = true
|
||||
transport.start()
|
||||
// when-then
|
||||
shouldThrow<CancellationException> {
|
||||
transport.close()
|
||||
}
|
||||
|
||||
transport.currentState shouldBe ClientTransportState.ShutdownFailed
|
||||
}
|
||||
|
||||
@Test
|
||||
fun `should call onClose even when CancellationException is thrown`() = runTest {
|
||||
var onCloseCalled = false
|
||||
transport.onClose { onCloseCalled = true }
|
||||
transport.shouldThrowCancellation = true
|
||||
transport.start()
|
||||
|
||||
shouldThrow<CancellationException> {
|
||||
transport.close()
|
||||
}
|
||||
|
||||
onCloseCalled shouldBe true
|
||||
}
|
||||
}
|
||||
|
||||
@Nested
|
||||
@DisplayName("State Transitions")
|
||||
inner class StateTransitionTests {
|
||||
|
||||
@ParameterizedTest
|
||||
@CsvSource(
|
||||
"New, Initializing",
|
||||
"New, Stopped",
|
||||
"Initializing, Operational",
|
||||
"Initializing, InitializationFailed",
|
||||
"Operational, ShuttingDown",
|
||||
"ShuttingDown, Stopped",
|
||||
"ShuttingDown, ShutdownFailed",
|
||||
)
|
||||
fun `should allow valid transitions`(fromName: String, toName: String) {
|
||||
val from = ClientTransportState.valueOf(fromName)
|
||||
val to = ClientTransportState.valueOf(toName)
|
||||
|
||||
transport.forceState(from)
|
||||
transport.testStateTransition(from, to)
|
||||
|
||||
transport.currentState shouldBe to
|
||||
}
|
||||
|
||||
@ParameterizedTest
|
||||
@CsvSource(
|
||||
// From New: only Initializing is valid
|
||||
"New, Operational",
|
||||
"New, InitializationFailed",
|
||||
"New, ShuttingDown",
|
||||
"New, ShutdownFailed",
|
||||
// From Initializing: only Operational or InitializationFailed are valid
|
||||
"Initializing, New",
|
||||
"Initializing, Initializing",
|
||||
"Initializing, ShuttingDown",
|
||||
"Initializing, Stopped",
|
||||
"Initializing, ShutdownFailed",
|
||||
// From Operational: only ShuttingDown is valid
|
||||
"Operational, New",
|
||||
"Operational, Initializing",
|
||||
"Operational, InitializationFailed",
|
||||
"Operational, Operational",
|
||||
"Operational, Stopped",
|
||||
"Operational, ShutdownFailed",
|
||||
// From ShuttingDown: only Stopped or ShutdownFailed are valid
|
||||
"ShuttingDown, New",
|
||||
"ShuttingDown, Initializing",
|
||||
"ShuttingDown, InitializationFailed",
|
||||
"ShuttingDown, Operational",
|
||||
"ShuttingDown, ShuttingDown",
|
||||
// From terminal states: no transitions allowed
|
||||
"InitializationFailed, New",
|
||||
"InitializationFailed, Operational",
|
||||
"Stopped, New",
|
||||
"Stopped, Operational",
|
||||
"ShutdownFailed, New",
|
||||
"ShutdownFailed, Operational",
|
||||
)
|
||||
fun `should reject invalid transitions`(fromName: String, toName: String) {
|
||||
val from = ClientTransportState.valueOf(fromName)
|
||||
val to = ClientTransportState.valueOf(toName)
|
||||
|
||||
transport.forceState(from)
|
||||
|
||||
val exception = shouldThrow<IllegalArgumentException> {
|
||||
transport.testStateTransition(from, to)
|
||||
}
|
||||
exception.message shouldContain "Invalid transition: $from → $to"
|
||||
}
|
||||
}
|
||||
|
||||
@Nested
|
||||
@DisplayName("Send Operations")
|
||||
inner class SendTests {
|
||||
|
||||
@Test
|
||||
fun `should send message successfully when OPERATIONAL`() = runTest {
|
||||
val message = PingRequest().toJSON()
|
||||
|
||||
transport.start()
|
||||
transport.send(message)
|
||||
|
||||
transport.sentMessages shouldBe listOf(message)
|
||||
}
|
||||
|
||||
@Test
|
||||
fun `should pass options to performSend`() = runTest {
|
||||
val message = PingRequest().toJSON()
|
||||
val options = TransportSendOptions()
|
||||
|
||||
transport.start()
|
||||
transport.send(message, options)
|
||||
|
||||
transport.sentMessages shouldBe listOf(message)
|
||||
transport.lastSendOptions shouldBe options
|
||||
}
|
||||
|
||||
@Test
|
||||
fun `should throw when sending before start`() = runTest {
|
||||
val exception = shouldThrow<McpException> {
|
||||
transport.send(PingRequest().toJSON())
|
||||
}
|
||||
|
||||
exception.code shouldBe RPCError.ErrorCode.CONNECTION_CLOSED
|
||||
exception.message shouldContain "Transport is not ready"
|
||||
}
|
||||
|
||||
@Test
|
||||
fun `should throw when sending after close`() = runTest {
|
||||
transport.start()
|
||||
transport.close()
|
||||
|
||||
val exception = shouldThrow<McpException> {
|
||||
transport.send(PingRequest().toJSON())
|
||||
}
|
||||
|
||||
exception.code shouldBe RPCError.ErrorCode.CONNECTION_CLOSED
|
||||
exception.message shouldContain "Transport is not ready"
|
||||
}
|
||||
|
||||
@ParameterizedTest
|
||||
@EnumSource(
|
||||
value = ClientTransportState::class,
|
||||
names = ["Operational"],
|
||||
mode = EnumSource.Mode.EXCLUDE,
|
||||
)
|
||||
fun `should throw when sending in non-OPERATIONAL state`(state: ClientTransportState) = runTest {
|
||||
transport.forceState(state)
|
||||
|
||||
val exception = shouldThrow<McpException> {
|
||||
transport.send(PingRequest().toJSON())
|
||||
}
|
||||
|
||||
exception.code shouldBe RPCError.ErrorCode.CONNECTION_CLOSED
|
||||
exception.message shouldContain "Transport is not ready"
|
||||
transport.sentMessages.isEmpty() shouldBe true
|
||||
}
|
||||
|
||||
@Test
|
||||
fun `should call onError when performSend throws McpException`() = runTest {
|
||||
var errorCallCount = 0
|
||||
var capturedError: Throwable? = null
|
||||
transport.onError { error ->
|
||||
errorCallCount++
|
||||
capturedError = error
|
||||
}
|
||||
transport.shouldFailSend = true
|
||||
transport.sendException = McpException(RPCError.ErrorCode.INTERNAL_ERROR, "Send failed")
|
||||
|
||||
transport.start()
|
||||
val exception = shouldThrow<McpException> {
|
||||
transport.send(PingRequest().toJSON())
|
||||
}
|
||||
|
||||
errorCallCount shouldBe 1
|
||||
capturedError shouldBe transport.sendException
|
||||
exception shouldBe transport.sendException
|
||||
}
|
||||
|
||||
@ParameterizedTest
|
||||
@MethodSource("io.modelcontextprotocol.kotlin.sdk.shared.AbstractClientTransportTest#nonMcpExceptions")
|
||||
fun `should call onError when performSend throws non-MCP exception`(testException: Throwable) = runTest {
|
||||
var errorCallCount = 0
|
||||
var capturedError: Throwable? = null
|
||||
transport.onError { error ->
|
||||
errorCallCount++
|
||||
capturedError = error
|
||||
}
|
||||
transport.shouldFailSend = true
|
||||
transport.sendException = testException
|
||||
|
||||
transport.start()
|
||||
val exception = shouldThrow<McpException> {
|
||||
transport.send(PingRequest().toJSON())
|
||||
}
|
||||
|
||||
errorCallCount shouldBe 1
|
||||
capturedError shouldBe testException
|
||||
exception.code shouldBe RPCError.ErrorCode.INTERNAL_ERROR
|
||||
exception.cause shouldBe testException
|
||||
}
|
||||
|
||||
@Test
|
||||
fun `should NOT call onError when performSend throws CancellationException`() = runTest {
|
||||
var errorCallCount = 0
|
||||
transport.onError { errorCallCount++ }
|
||||
transport.shouldFailSend = true
|
||||
transport.sendException = CancellationException("Operation cancelled")
|
||||
|
||||
transport.start()
|
||||
shouldThrow<CancellationException> {
|
||||
transport.send(PingRequest().toJSON())
|
||||
}
|
||||
|
||||
errorCallCount shouldBe 0
|
||||
}
|
||||
}
|
||||
|
||||
@Nested
|
||||
@DisplayName("Idempotency")
|
||||
inner class IdempotencyTests {
|
||||
|
||||
@Test
|
||||
fun `should be idempotent when closing from NEW state`() = runTest {
|
||||
transport.close()
|
||||
|
||||
transport.currentState shouldBe ClientTransportState.Stopped
|
||||
transport.closeResourcesCalled shouldBe false
|
||||
}
|
||||
|
||||
@Test
|
||||
fun `should be idempotent when closing from INITIALIZATION_FAILED state`() = runTest {
|
||||
transport.shouldFailInitialization = true
|
||||
shouldThrow<TestException> { transport.start() }
|
||||
|
||||
transport.close()
|
||||
|
||||
transport.currentState shouldBe ClientTransportState.InitializationFailed
|
||||
// closeResources was called during a failed start, but not during this close
|
||||
transport.closeResourcesCallCount shouldBe 1
|
||||
}
|
||||
|
||||
@ParameterizedTest
|
||||
@EnumSource(
|
||||
value = ClientTransportState::class,
|
||||
names = ["ShuttingDown", "ShutdownFailed", "Stopped"],
|
||||
)
|
||||
fun `should be idempotent when closing from terminal or shutdown states`(state: ClientTransportState) =
|
||||
runTest {
|
||||
transport.forceState(state)
|
||||
val initialCloseCount = transport.closeResourcesCallCount
|
||||
|
||||
transport.close()
|
||||
|
||||
transport.currentState shouldBe state
|
||||
transport.closeResourcesCallCount shouldBe initialCloseCount
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Simple test implementation of [AbstractClientTransport] for behavioral testing.
|
||||
* Tracks method calls without mocking frameworks.
|
||||
*/
|
||||
@OptIn(InternalMcpApi::class)
|
||||
private class TestClientTransport : AbstractClientTransport() {
|
||||
override val logger: KLogger = KotlinLogging.logger {}
|
||||
val sentMessages = mutableListOf<JSONRPCMessage>()
|
||||
var lastSendOptions: TransportSendOptions? = null
|
||||
var initializeCalled = false
|
||||
var closeResourcesCalled = false
|
||||
var closeResourcesCallCount = 0
|
||||
var shouldFailInitialization = false
|
||||
var shouldFailClose = false
|
||||
var shouldThrowCancellation = false
|
||||
var shouldFailSend = false
|
||||
var sendException: Throwable? = null
|
||||
|
||||
val currentState: ClientTransportState
|
||||
get() = state
|
||||
|
||||
override suspend fun initialize() {
|
||||
initializeCalled = true
|
||||
if (shouldFailInitialization) {
|
||||
throw TestException("Initialization failed")
|
||||
}
|
||||
}
|
||||
|
||||
override suspend fun performSend(message: JSONRPCMessage, options: TransportSendOptions?) {
|
||||
if (shouldFailSend) {
|
||||
throw sendException ?: TestException("Send failed")
|
||||
}
|
||||
sentMessages.add(message)
|
||||
lastSendOptions = options
|
||||
}
|
||||
|
||||
override suspend fun closeResources() {
|
||||
closeResourcesCalled = true
|
||||
closeResourcesCallCount++
|
||||
|
||||
when {
|
||||
shouldThrowCancellation -> throw CancellationException("Test cancellation")
|
||||
shouldFailClose -> throw TestException("Close failed")
|
||||
}
|
||||
}
|
||||
|
||||
fun testStateTransition(from: ClientTransportState, to: ClientTransportState) {
|
||||
stateTransition(from, to)
|
||||
}
|
||||
|
||||
fun forceState(newState: ClientTransportState) = updateState(newState)
|
||||
}
|
||||
|
||||
private class TestException(message: String) : Exception(message)
|
||||
}
|
||||
Loading…
Reference in a new issue