Skip to content

fix(client): treat a 404 on an SSE resume GET as session expired - #1477

Open
BlueX888 wants to merge 1 commit into
modelcontextprotocol:mainfrom
BlueX888:contrib/get-404-session-expired
Open

BlueX888 wants to merge 1 commit into
modelcontextprotocol:mainfrom
BlueX888:contrib/get-404-session-expired

Conversation

@BlueX888

@BlueX888 BlueX888 commented Nov 19, 2026 •

Copy link
Copy Markdown
Contributor

Fixes #1476.

Problem

A legacy Streamable HTTP session that the server has terminated answers the client's SSE resume GET with 404 (the transports spec requires this). Both built-in clients mapped that to a generic HTTP error, classify_reconnect_error classified it as retryable, and the default exponential backoff has no maximum. The resume GET was retried with the same stale session, initialize was never sent again, and the in-flight request never resolved.

Changes

  • common/reqwest/streamable_http_client.rs, common/unix_socket.rs: map 404 with an attached session to StreamableHttpError::SessionExpired in the GET path, mirroring the existing POST mapping. A 404 without a session keeps the previous behavior.
  • streamable_http_client.rs:
    • classify_reconnect_error treats SessionExpired as terminal, so the reconnect loop stops.
    • A pending request interrupted by a session-expired stream now fails with SessionExpired instead of the generic "stream closed before its final response" error. It is not replayed: the original POST already ran and its response stream is gone, so a retry could duplicate a non-idempotent tool call.
    • When reinit_on_expired_session is enabled, the existing POST-404 recovery is reused to re-initialize once and restart the listener. GET-triggered recovery is limited to one attempt per session_recovery_timeout, so a server that keeps answering 404 for replacement listeners cannot drive an initialize hot loop. POST-triggered recovery keeps its existing semantics. New ordinary POSTs are also held while a GET-triggered recovery is pending, so they are not sent on the known-expired session.
    • The bound lives in stream_recovery_allowed; changing the policy (for example, only after a POST succeeds on the replacement session) is a one-function change.
    • Added a warning when session recovery fails, so a failed re-initialization is visible in logs.

Testing

  • tests/test_streamable_http_get_404_session_expired.rs: real reqwest client against an axum mock. Covers reinit disabled (resume_gets == 1, prompt fails promptly), reinit enabled (exactly one extra initialize, listener restarted on the new session), and an initial listener 404 (one recovery, no hot loop).
  • tests/test_streamable_http_reconnect_classification.rs: scripted client cases for the same three paths, including the rate limit.
  • tests/test_unix_socket_transport.rs: a GET with a session gets SessionExpired; without a session it still gets UnexpectedServerResponse.
  • A slow-in-flight-POST case: a third call submitted during GET-triggered recovery is posted only after the session is replaced (reverting the admission gate makes it go out on the old session and fail the test).
  • Two unit tests: terminal classification for SessionExpired with a transient-error counterexample, and the recovery rate limiter.

The new tests fail on the parent commit for the expected reasons (the e2e cases time out with the pending request still alive; the established-listener case retries the same session; the Unix socket case gets UnexpectedServerResponse("get_stream returned 404 ...")). They pass at this head. Removing the terminal classification as a negative control reproduces the hang.

Commands run at this head:

cargo test --test test_streamable_http_get_404_session_expired --no-default-features --features 'client,transport-streamable-http-client,transport-streamable-http-client-reqwest'  # 3 passed
cargo test --test test_streamable_http_reconnect_classification --no-default-features --features 'client,transport-streamable-http-client'  # 14 passed
cargo test --test test_unix_socket_transport --no-default-features --features 'client,server,transport-streamable-http-client-unix-socket'  # 9 passed
cargo test -p rmcp --lib --no-default-features  # 206 passed
cargo +nightly fmt --all -- --check
cargo clippy -p rmcp --all-targets --features '<CI no-local set>' -- -D warnings
RUSTDOCFLAGS="-D warnings" cargo doc -p rmcp --no-deps --all-features

cargo test -p rmcp --all-features also passes; note that the repo's local feature makes some streamable tests compile empty, so the no-local feature set above is the meaningful run.

Known limits

  • A custom StreamableHttpClient implementation must return SessionExpired itself for a 404 with an attached session; this is documented on the trait but not exercised by a test.
  • The interrupted request is failed, not replayed, matching the existing POST-404 choice.
  • A canceled request whose stream ends with SessionExpired still triggers recovery; that cross-case has no dedicated test.
  • The Unix socket test covers the GET mapping; full worker recovery is covered by the reqwest e2e.

Prepared with AI assistance (Claude Code) under the BlueX888 GitHub account.

@BlueX888
BlueX888 requested a review from a team as a code owner November 19, 2026 19:31
@github-actions github-actions Bot added T-test Testing related changes T-core Core library changes T-transport Transport layer changes labels Nov 19, 2026
@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Nov 19, 2026 •

Copy link
Copy Markdown
Codex Review Summary: ✅ Completed

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-11-19T19:52:30.688587Z 57b0acc New commits
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

@github-actions

Copy link
Copy Markdown
Contributor

@michaelneale is on triage rotation this week and is the reviewer for this one.

Labels come from the PR labeler. Please review the change.

Automated triage. Labels are a first pass and the assigned maintainer has the final say.

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 8ee6405232

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

)
{
last_stream_recovery = Some(tokio::time::Instant::now());
recovery_requested = true;

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

P2 Badge Pause ordinary POSTs when stream recovery is requested

With reinitialization enabled, if a GET reports session expiry while another POST is still draining, this flag does not stop new ordinary POSTs: may_start and may_receive check the POST recovery queue but not recovery_requested, and that queue is empty for GET-only recovery. Subsequent calls are therefore sent with the known-expired session instead of waiting for its replacement. If they remain in flight past the already-running recovery deadline, they are canceled with SessionRecoveryTimeout and are not retried, unnecessarily failing new calls. Include recovery_requested in the ordinary-POST admission gate so GET-triggered recovery quiesces traffic like POST-triggered recovery.

Useful? React with 👍 / 👎.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

Fixed in 6c57414: may_start now also requires !recovery_requested, so ordinary POSTs wait for a GET-triggered recovery just as they do for a POST-triggered one. Added a regression test with a slow in-flight POST, an interrupted POST whose resume gets 404, and a third call submitted during recovery; the third call is posted on session-2. Reverting the gate makes the new test fail (posted on session-1). Classification suite 14 passed, e2e 3 passed, Unix socket 9 passed, nightly fmt clean.

@BlueX888
BlueX888 force-pushed the contrib/get-404-session-expired branch from 8ee6405 to 6c57414 Compare November 19, 2026 19:44
A resume or listener GET carrying Mcp-Session-Id that answers 404 means the
server terminated the session (transports spec, Session Management). Both
built-in clients mapped it to a generic HTTP error, so the reconnect loop
retried the dead session forever and the in-flight request never resolved.

Map 404 with an attached session to SessionExpired in the reqwest and Unix
socket GET paths, matching the POST mapping; make SessionExpired terminal in
classify_reconnect_error; fail the interrupted request with a session-expired
error instead of the generic "stream closed" message; and reuse the existing
POST-404 recovery to re-initialize once and restart the listener. Recovery is
bounded to one attempt per session_recovery_timeout so a server that keeps
answering 404 for replacement listeners cannot drive an initialize hot loop.

New ordinary POSTs are held while a stream-triggered recovery is pending,
so they are not sent on the known-expired session.
@BlueX888
BlueX888 force-pushed the contrib/get-404-session-expired branch from 6c57414 to 57b0acc Compare November 19, 2026 19:46

@jokemanfire jokemanfire left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

Reviewed and ran at head 57b0acc (checked out the PR head).

Verified

  • cargo test --test test_streamable_http_get_404_session_expired --no-default-features --features 'client,transport-streamable-http-client,transport-streamable-http-client-reqwest' → 3 passed.
  • cargo test --test test_streamable_http_reconnect_classification --no-default-features --features 'client,transport-streamable-http-client' → 14 passed (includes stream_recovery_pauses_new_posts_until_the_replacement_session_is_ready).
  • cargo test --test test_unix_socket_transport --no-default-features --features 'client,server,transport-streamable-http-client-unix-socket' → 9 passed.
  • Negative control: removing | StreamableHttpError::SessionExpired from classify_reconnect_error makes resume_get_404_fails_pending_request_with_session_expired and resume_get_404_reinitializes_once_and_restarts_listener fail with ping must resolve instead of hanging on resume retries: Elapsed(()). So the terminal classification is what turns the hang into a prompt error, and the tests are not passing for an unrelated reason.
  • Read the 404 mapping in both common/reqwest/streamable_http_client.rs:144-146 and common/unix_socket.rs:536-538; both are guarded by session_was_attached, matching the POST mapping at reqwest/streamable_http_client.rs:326-328. A 404 with no session keeps its old error, as the PR says.

One design question, not a blocker

The rate limiter is event-driven, not scheduled. last_stream_recovery is set when recovery is requested, and after a successful recovery the worker only spawns the replacement listener. If that replacement listener also answers 404 within session_recovery_timeout, stream_recovery_allowed is false, no recovery is requested, and the listener stays down with no timer to retry it. A subsequent POST that gets 404 can still trigger the POST path, but an idle client stops receiving server-initiated messages until it sends something.

Is that intended? The test initial_listener_get_404_reinitializes_at_most_once asserts exactly two inits after 100 ms, so it covers the hot-loop bound but not what happens after the timeout. If the intent is “one attempt per window, then try again when the window expires”, the worker needs a delayed wake-up (or a reconnect backoff that keeps a timer). If the intent is “one attempt, then live until traffic proves the session works”, it would be worth saying that in the reinit_on_expired_session docs, because “at most once per session_recovery_timeout” reads like a retry window rather than a single shot.

Nits

  • The interrupted request is failed with ErrorData::internal_error("Session expired (HTTP 404)"). Since the error is client-generated, not a server internal error, a dedicated message/code or transport_closed-style marker would make it easier for callers to distinguish “session went away” from “the server returned -32603”. The test only asserts on the message text, so changing this later is safe.
  • The body already lists the custom-StreamableHttpClient and canceled-request gaps honestly; nothing else I tried contradicted them.

I have not approved this PR; the question above is about intended semantics, not a defect I can demonstrate.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

T-core Core library changes T-test Testing related changes T-transport Transport layer changes

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Streamable HTTP client retries a session-expired (404) SSE resume GET forever and never re-initializes

2 participants