fix(streamable-http): prevent SSE reconnect loops with shadow channels

[its-mash]

Summary

Fixes infinite SSE reconnect loops caused by multiple competing EventSource connections in the Streamable HTTP server session layer. Tested with Cursor, VS Code, and Claude Desktop.

Problem

When the server sends POST SSE responses with a retry field (priming event), the browser's EventSource API automatically reconnects via GET after the stream ends. This creates multiple competing EventSource connections — one from the initial standalone GET, and additional ones from completed POST responses (initialize, tools/list, etc.).

Each reconnecting GET called resume() which replaced self.common.tx (the common channel sender). Dropping the old sender closed the old receiver, terminating the OTHER EventSource's stream. Both reconnected every sse_retry seconds (3s), leapfrogging each other in an infinite loop.

Root Cause Analysis

The connection lifecycle that causes the loop:

1. Client sends POST initialize → SSE response with priming (retry: 3000) → stream ends
2. Client sends GET (standalone) → becomes primary common channel
3. POST EventSource reconnects via GET (3s later) → replaces common.tx → kills stream from step 2
4. GET from step 2's EventSource reconnects → replaces common.tx → kills stream from step 3
5. Repeat every 3 seconds indefinitely

Solution — Shadow Channels

Instead of always replacing the common channel sender on resume, the new resume_or_shadow_common() method checks whether the primary common channel is still active:

• Primary dead (tx.is_closed()) → Replace it. The new stream becomes the primary notification channel.
• Primary alive → Create a shadow stream — an idle SSE connection kept alive by SSE keep-alive pings (: comments) that does NOT receive notifications and does NOT replace the primary channel.

Shadow streams prevent competing EventSource connections from killing each other while keeping the HTTP connections alive (so EventSource doesn't reconnect again).

Changes

Commit	Description
8bd424e	Initial 409 Conflict approach (returned error on duplicate standalone stream)
0d03eb5	Handle resume with completed request-wise channels (fall through to common)
a7bb822	Remove 409 Conflict — allow channel replacement per MCP spec ("client MAY remain connected to multiple SSE streams")
7cf5406	Skip cache replay (sync) when replacing active streams (replaying list_changed notifications caused notification loops)
a7df58c	Shadow channels — the final fix that prevents the leapfrog loop entirely

Key Design Decisions

1. No cache replay on common channel resume: Server-initiated notifications (tools/list_changed, resources/list_changed) are idempotent signals. Replaying cached ones causes clients to re-process old events, triggering unnecessary re-fetches. Missing one is harmless — the next real event will arrive naturally.

2. Shadow streams are idle: They don't receive notifications — only the primary common channel does. This is intentional: the reconnecting POST EventSources don't need notifications (their purpose — delivering the POST response — is already fulfilled). They just need to stay alive so EventSource stops reconnecting.

3. Automatic cleanup: Closed shadow senders (from client disconnection) are cleaned up via retain(!is_closed()) on each resume() call and clear() on close_sse_stream().

4. Request-wise channels still sync: Only the common channel skips replay. Request-wise channels (POST response streams) still use sync() for proper resumption, since those carry actual request/response data that may need replay.

Files Changed

• crates/rmcp/src/transport/streamable_http_server/session/local.rs
  • Added shadow_txs: Vec<Sender<ServerSseMessage>> to LocalSessionWorker
  • New method resume_or_shadow_common() with primary-alive check
  • Updated resume() to use shadow logic for both direct common and request-wise fallback paths
  • Updated close_sse_stream() to clear shadow senders
  • Updated create_local_session() to initialize shadow_txs

Test Plan

• Cursor connects and initializes successfully (no 409/500 errors)
• Cursor does NOT enter infinite GET reconnect loop after connection
• Feature changes trigger exactly one batch of list_changed notifications
• Cursor receives and processes notifications correctly (re-fetches tools/resources)
• No notification replay loop (no repeated ResourceListChanged every 3s)
• VS Code connects and works correctly (unaffected by changes)
• cargo check --workspace passes

[DaleSeo]

Thanks for addressing my feedback, @its-mash. The code looks great now! I just have a couple of small suggestions.

To fix the failing checks, please rebase your branch onto the latest main. I think it's because we recently upgraded to reqwest 0.13.

[DaleSeo]

Shadow streams are idle by design. They don’t receive notifications, just SSE keep-alive pings. However, they still get the full channel_capacity here.

Since only the primary replacement path needs that full capacity, we might want to use a minimal buffer for shadows:

Suggested change

	let (tx, rx) = tokio::sync::mpsc::channel(self.session_config.channel_capacity);
	let is_replacing_dead_primary = self.common.tx.is_closed();
	let capacity = if is_replacing_dead_primary {
	self.session_config.channel_capacity
	} else {
	1 // Shadow streams only need keep-alive pings
	};
	let (tx, rx) = tokio::sync::mpsc::channel(capacity);

[its-mash]

agree, updated

[DaleSeo]

The shadow_txs: Vec<Sender<ServerSseMessage>> vector can grow indefinitely. If a client misbehaves or has a bug, it could open hundreds of GET streams, each creating a new sender. The cleanup with retain(!is_closed()) only happens at the beginning of resume(), so there's a period when all shadows are active at the same time. It would be helpful to add an upper limit.

Suggested change

	self.shadow_txs.push(tx);
	const MAX_SHADOW_STREAMS: usize = 32;
	if self.shadow_txs.len() >= MAX_SHADOW_STREAMS {
	tracing::warn!(
	shadow_count = self.shadow_txs.len(),
	"Shadow stream limit reached, dropping oldest"
	);
	self.shadow_txs.remove(0);
	}
	self.shadow_txs.push(tx);

[its-mash]

agree, updated

[alexhancock]

@its-mash Can you fix this minor lint issue

error: this import is redundant
  --> crates/rmcp/tests/test_sse_concurrent_streams.rs:18:1
   |
18 | use reqwest;
   | ^^^^^^^^^^^^ help: remove it entirely
   |
   = help: for further information visit https://rust-lang.github.io/rust-clippy/master/index.html#single_component_path_imports
   = note: `-D clippy::single-component-path-imports` implied by `-D warnings`
   = help: to override `-D warnings` add `#[allow(clippy::single_component_path_imports)]`