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