refactor: Introduce AbstractClientTransport and simplify client transport lifecycle (#517) (#516)

## 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:
Konstantin Pavlov 2026-02-13 13:08:26 +02:00 • committed by GitHub
commit 6120b3109e
No known key found for this signature in database
GPG key ID: B5690EEEBB952194

View file

@ -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)
}