Skip to content

fix(transport): hold inbound messages until the client transport is operational - #1207

Merged
devcrocod merged 4 commits into
mainfrom
fix/channel-transport-start-race
Nov 20, 2026
Merged

devcrocod merged 4 commits into
mainfrom
fix/channel-transport-start-race

Conversation

@e5l

@e5l e5l commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

Why

Follow-up to #985. Goal: remove the CI flake that makes PRs on the stateless branch green only on rerun. RequestScopedLifecycleTest and ResponseCacheTest fail with "server/discover probe timed out" or "Expected 2026-07-28 but actual was null". Every failing log has Error handling request: server/discover ... McpException: Transport is not ready from AbstractClientTransport.send. The defect is on main.

AbstractClientTransport.start() runs initialize(), where transports start their readers, and only then moves to Operational. A reader can hand a request to Protocol in that window. The handler's reply hits the state check in send() and is dropped, so the peer waits out its timeout. Sometimes the error reply gets through instead, and the client reads it as a refusal and falls back to legacy. The integration tests start server.createSession and client.connect concurrently over ChannelTransport, and slow CI runners widen the window.

What changed

  • AbstractClientTransport overrides onMessage so that handlers wait on a deferred that start() completes right after the Operational transition. Nothing changes once the transport is running.
  • ABI dump: AbstractClientTransport now declares the onMessage it already inherited (a binary-compatible addition).
  • Removed the comment in ProtocolConcurrencyIntegrationTest that described early delivery. It no longer holds.

Scope

The fix goes in the base class because the pattern is shared. ChannelTransport and StdioClientTransport both start readers in initialize() and deliver before Operational. SseClientTransport can too, once the endpoint event has arrived. StreamableHttpClientTransport delivers only after a send, so it is unaffected. Server transports extend AbstractTransport, which has no state gate on send.

Tradeoffs

A subclass whose initialize() waits for a JSON-RPC message to be handled would now block. No transport in this repo does that. The closest case is an SSE server that breaks the spec by sending a JSON-RPC event before endpoint: start() would now hang instead of losing the reply. Fixing this per transport instead would mean overriding start(), which its KDoc forbids, and repeating the same fix in every reader.

Blast Radius

All AbstractClientTransport subclasses, including third-party ones, now get inbound messages only after start() returns. Delivery after that is unchanged.

Verification

  • ChannelTransportTest.answers a request the peer sent before start returned runs the event loop on its own scheduler while start() is suspended. Before the fix: Expected JSONRPCResponse(id=NumberId(value=1), ...) but actual was null, with Transport is not ready in the log. Passes after the fix (JVM, JS, Wasm).
  • AbstractClientTransportTest.should answer a message received during initialization once OPERATIONAL. Before the fix: expected:<[JSONRPCResponse(...)]> but was:<[]>. Passes after the fix.
  • Local: jvmTest for core, testing, client, server and integration-test, plus ktlintCheck detekt checkKotlinAbi, all green.
  • CI on ec7a026: Build (Linux and iOS simulator) and Conformance, both green.
  • Stress loop on the stateless branch: the flake hit 10 of 131 baseline runs and 0 of 131 runs with this fix, and every baseline failure logged Transport is not ready. Details in this comment.

🤖 Generated with Claude Code

e5l and others added 2 commits November 18, 2026 13:40
A client transport delivers inbound messages from readers started in
initialize(), while send() refuses until start() marks it Operational.
A request that arrives in that window gets a reply that is never sent.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…perational

Readers started in initialize() could hand a request to the protocol
before start() moved the transport to Operational, so the reply failed
with "Transport is not ready" and the peer waited out its timeout.
AbstractClientTransport now delivers to onMessage handlers only after
start() completes, which covers ChannelTransport, StdioClientTransport
and the other client transports.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Copilot AI balanced review requested due to automatic review settings November 18, 2026 13:02

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

Early SSE notifications can block endpoint discovery, and failed initialization can leave pending deliveries suspended, causing hangs.

2 open issues
What changed in this PR

Addresses the client-transport startup race behind intermittent discovery failures following #985. The change delays inbound callbacks until the transport becomes operational, allowing handlers to send replies.

Changes:

  • Adds a readiness gate to AbstractClientTransport.
  • Adds regression tests for messages received during initialization.
  • Updates public API dumps for the onMessage override.
File Description
kotlin-sdk-testing/​src/​commonTest/​kotlin/​io/​modelcontextprotocol/​kotlin/​sdk/​testing/​ChannelTransportTest.kt Tests an early request using separately controlled schedulers.
kotlin-sdk-core/​src/​jvmTest/​kotlin/​io/​modelcontextprotocol/​kotlin/​sdk/​shared/​AbstractClientTransportTest.kt Tests replying to a message received during initialization.
kotlin-sdk-core/​src/​commonMain/​kotlin/​io/​modelcontextprotocol/​kotlin/​sdk/​shared/​AbstractClientTransport.kt Gates inbound callbacks on the operational transition.
kotlin-sdk-core/​api/​kotlin-sdk-core.klib.api Records the override in the Kotlin library API dump.
kotlin-sdk-core/​api/​kotlin-sdk-core.api Records the override in the JVM API dump.

Review effort: Balanced

*/
public override fun onMessage(block: suspend (JSONRPCMessage) -> Unit) {
super.onMessage { message ->
operational.await()
*/
public override fun onMessage(block: suspend (JSONRPCMessage) -> Unit) {
super.onMessage { message ->
operational.await()
…e start

Client transports now hold inbound messages until start() completes, so
the note describing early delivery no longer holds.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Copilot AI balanced review requested due to automatic review settings November 18, 2026 14:45

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔵 Needs a closer look

Failed or cancelled initialization can leave readers suspended and cleanup hanging, while an early SSE notification can deadlock startup.

2 open issues
1 previously missed issue

In code that hasn't changed since last review

Low severity Correct the claim that message delivery starts after start() returns

kotlin-sdk-core/​src/​commonMain/​kotlin/​io/​modelcontextprotocol/​kotlin/​sdk/​shared/​AbstractClientTransport.kt:148

Completing the deferred can resume a waiting handler before start() returns; the new UnconfinedTestDispatcher test exercises exactly that ordering. This contradicts the blast-radius statement that inbound messages are delivered only after start() returns, which would let consumers assume callback state set after the call is ready. Please correct that statement to say delivery begins once the state is operational, or provide the stronger guarantee if intended.

Review effort: Balanced

@e5l

e5l commented Nov 18, 2026

Copy link
Copy Markdown
Contributor Author

Stress loop on the stateless branch

The fix and test commits were cherry-picked onto devcrocod/sep-2575-stateless-mcp at f0e5530. Both applied cleanly, ABI dumps included. Each iteration ran ./gradlew :integration-test:jvmTest --rerun on the baseline and fixed trees at the same time, so both saw the same load. The machine had 16 cores, with 48 yes processes for load and Gradle under nice -n 15 --no-daemon, so the test JVMs got starved CPU. "Flake" means a failure in RequestScopedLifecycleTest or ResponseCacheTest.

Round Baseline runs Baseline flake Baseline Transport is not ready Fix runs Fix flake Fix not ready
1 30 5 5 30 0 0
2 30 1 1 30 0 0
3 (stopped early) 11 0 0 11 0 0
4 30 1 1 30 0 0
5 (worktrees swapped) 30 3 3 30 0 0
Total 131 10 10 131 0 0
  • The baseline failures match CI: The server/discover probe timed out, a legacy fallback that shows up as a missing server identity or wrong log delivery, and ResponseCacheTest counts off by one. Every failing baseline run logged Transport is not ready, and no passing run did. One-sided Fisher p = 0.0008.
  • Running only the two classes with 32 load processes and no nice gave 0/30 failures on both trees. Without the full suite saturating Dispatchers.Default, the window doesn't open on this machine.

Separate, pre-existing leak. Both trees sometimes fail 2-3 unrelated runTest tests with IllegalStateException: Not connected from SessionNotificationJob.handleSendNotificationEvent → Protocol.notification. Logging probes on both trees traced it to AbstractServerFeaturesTest sessions over InMemoryTransport. tearDown closes the client while a list-changed send is in flight. Neither end is an AbstractClientTransport, so this change is not on that path. The leak rate follows the worktree slot, not the code: about 9-10% in one slot and 1-3% in the other, whichever code it held. The same job and teardown are on main.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

@devcrocod devcrocod left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

lgtm

@devcrocod
devcrocod merged commit a3399b9 into main Nov 20, 2026
20 checks passed
@devcrocod
devcrocod deleted the fix/channel-transport-start-race branch November 20, 2026 19:31
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants