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

@ -139,6 +139,9 @@ public final class io/modelcontextprotocol/kotlin/sdk/InitializedNotification {
public static synthetic fun Params$default (Lio/modelcontextprotocol/kotlin/sdk/InitializedNotification;Lkotlinx/serialization/json/JsonObject;ILjava/lang/Object;)Lio/modelcontextprotocol/kotlin/sdk/types/BaseNotificationParams;
}
public abstract interface annotation class io/modelcontextprotocol/kotlin/sdk/InternalMcpApi : java/lang/annotation/Annotation {
}
public final class io/modelcontextprotocol/kotlin/sdk/LibVersionKt {
public static final field LIB_VERSION Ljava/lang/String;
}
@ -408,16 +411,46 @@ public final class io/modelcontextprotocol/kotlin/sdk/internal/Utils_jvmKt {
public static final fun getIODispatcher ()Lkotlinx/coroutines/CoroutineDispatcher;
}
public abstract class io/modelcontextprotocol/kotlin/sdk/shared/AbstractClientTransport : io/modelcontextprotocol/kotlin/sdk/shared/AbstractTransport {
public fun <init> ()V
protected final fun checkState (Lio/modelcontextprotocol/kotlin/sdk/shared/ClientTransportState;Lkotlin/jvm/functions/Function1;)V
public static synthetic fun checkState$default (Lio/modelcontextprotocol/kotlin/sdk/shared/AbstractClientTransport;Lio/modelcontextprotocol/kotlin/sdk/shared/ClientTransportState;Lkotlin/jvm/functions/Function1;ILjava/lang/Object;)V
public fun close (Lkotlin/coroutines/Continuation;)Ljava/lang/Object;
protected abstract fun closeResources (Lkotlin/coroutines/Continuation;)Ljava/lang/Object;
protected abstract fun getLogger ()Lio/github/oshai/kotlinlogging/KLogger;
protected final fun getState ()Lio/modelcontextprotocol/kotlin/sdk/shared/ClientTransportState;
protected abstract fun initialize (Lkotlin/coroutines/Continuation;)Ljava/lang/Object;
protected abstract fun performSend (Lio/modelcontextprotocol/kotlin/sdk/types/JSONRPCMessage;Lio/modelcontextprotocol/kotlin/sdk/shared/TransportSendOptions;Lkotlin/coroutines/Continuation;)Ljava/lang/Object;
public static synthetic fun performSend$default (Lio/modelcontextprotocol/kotlin/sdk/shared/AbstractClientTransport;Lio/modelcontextprotocol/kotlin/sdk/types/JSONRPCMessage;Lio/modelcontextprotocol/kotlin/sdk/shared/TransportSendOptions;Lkotlin/coroutines/Continuation;ILjava/lang/Object;)Ljava/lang/Object;
public fun send (Lio/modelcontextprotocol/kotlin/sdk/types/JSONRPCMessage;Lio/modelcontextprotocol/kotlin/sdk/shared/TransportSendOptions;Lkotlin/coroutines/Continuation;)Ljava/lang/Object;
public fun start (Lkotlin/coroutines/Continuation;)Ljava/lang/Object;
protected final fun stateTransition (Lio/modelcontextprotocol/kotlin/sdk/shared/ClientTransportState;Lio/modelcontextprotocol/kotlin/sdk/shared/ClientTransportState;)V
protected final fun updateState (Lio/modelcontextprotocol/kotlin/sdk/shared/ClientTransportState;)V
}
public abstract class io/modelcontextprotocol/kotlin/sdk/shared/AbstractTransport : io/modelcontextprotocol/kotlin/sdk/shared/Transport {
public fun <init> ()V
protected final fun get_onClose ()Lkotlin/jvm/functions/Function0;
protected final fun get_onError ()Lkotlin/jvm/functions/Function1;
protected final fun get_onMessage ()Lkotlin/jvm/functions/Function2;
protected final fun invokeOnCloseCallback ()V
public fun onClose (Lkotlin/jvm/functions/Function0;)V
public fun onError (Lkotlin/jvm/functions/Function1;)V
public fun onMessage (Lkotlin/jvm/functions/Function2;)V
}
public final class io/modelcontextprotocol/kotlin/sdk/shared/ClientTransportState : java/lang/Enum {
public static final field InitializationFailed Lio/modelcontextprotocol/kotlin/sdk/shared/ClientTransportState;
public static final field Initializing Lio/modelcontextprotocol/kotlin/sdk/shared/ClientTransportState;
public static final field New Lio/modelcontextprotocol/kotlin/sdk/shared/ClientTransportState;
public static final field Operational Lio/modelcontextprotocol/kotlin/sdk/shared/ClientTransportState;
public static final field ShutdownFailed Lio/modelcontextprotocol/kotlin/sdk/shared/ClientTransportState;
public static final field ShuttingDown Lio/modelcontextprotocol/kotlin/sdk/shared/ClientTransportState;
public static final field Stopped Lio/modelcontextprotocol/kotlin/sdk/shared/ClientTransportState;
public static fun getEntries ()Lkotlin/enums/EnumEntries;
public static fun valueOf (Ljava/lang/String;)Lio/modelcontextprotocol/kotlin/sdk/shared/ClientTransportState;
public static fun values ()[Lio/modelcontextprotocol/kotlin/sdk/shared/ClientTransportState;
}
public abstract class io/modelcontextprotocol/kotlin/sdk/shared/Protocol {
public fun <init> (Lio/modelcontextprotocol/kotlin/sdk/shared/ProtocolOptions;)V
protected abstract fun assertCapabilityForMethod (Lio/modelcontextprotocol/kotlin/sdk/types/Method;)V