Skip to content

fix: cancel a terminated session's requests before closing its streams - #709

Open
yorzi wants to merge 1 commit into
modelcontextprotocol:mainfrom
yorzi:fix/session-teardown-cancellation-order
Open

yorzi wants to merge 1 commit into
modelcontextprotocol:mainfrom
yorzi:fix/session-teardown-cancellation-order

Conversation

@yorzi

@yorzi yorzi commented Nov 22, 2026

Copy link
Copy Markdown
Contributor

Follows #692 and #698: ending a session now cancels its requests before anything that can block, so a stalled stream no longer leaves them running, and a request waiting on a nested request ends cancelled instead of failing.

Fixes #708

Motivation and Context

When StreamableHTTPTransport removes a stateful session, cleanup_session_unsafe wakes the threads waiting on the session's server-to-client requests with :session_closed (lib/mcp/server/transports/streamable_http_transport.rb:2053), and release_session (:2071) then closes the GET and POST streams before it calls cancel_all_incoming. A close can take up to stream_write_timeout: (10 seconds by default, :2092) on a stalled peer, and the cancellation waits behind it. Two guarantees of the Cancellation page fail meanwhile:

  • A request that reaches the session as it ends (fix: cancel a request that reaches a session as it ends #698) is admitted and run: its tool runs with server_context.cancelled? false, and over SSE its result is written to its POST stream after the DELETE.
  • A request waiting on a nested server-to-client request is woken with :session_closed before its own token is cancelled: the nested call raises "SSE session closed while waiting" (:848), the handler sees cancelled? false, and the request is reported as an exception and recorded as an internal error rather than a cancellation. The wake-up runs before the cancellation even without a stalled stream, so this outcome depends on thread scheduling.

On main (00868f7), with a GET stream whose close blocks until released:

(a) DELETE=200 tool_calls(cancelled?)=[false] written="data: {\"jsonrpc\":\"2.0\",\"id\":9,\"result\":{...\"text\":\"ran\"...}}\n\n"
(b) handler saw=[["RuntimeError", false]]
    instrumentation(tools/call)=[{method: "tools/call", error: :internal_error}]
    reported=["RuntimeError: SSE session closed while waiting for elicitation/create response."]

With this change:

(a) DELETE=200 tool_calls(cancelled?)=[] written=""
(b) handler saw=[["MCP::CancelledError", true]]
    instrumentation(tools/call)=[{method: "tools/call", cancelled: true, cancellation_reason: "Session terminated"}]
    reported=[]

release_session now cancels the session's requests first, then wakes the remaining waits with :session_closed, then closes the streams. cleanup_session_unsafe collects those waits under the lock instead of waking them there; send_request registers a wait only for a session it finds under the lock, so none is added once the session is removed. A nested request is now woken through its parent's cancellation hook, so it raises MCP::CancelledError as it does after notifications/cancelled, and :session_closed still ends the waits that belong to no request (a send_request made outside a handler). Cancellations still run outside @mutex, as the existing "cancellation hooks of a terminated session's requests run outside the transport lock" test checks.

How Has This Been Tested?

New tests in test/mcp/server/transports/streamable_http_transport_test.rb, with a GET stream whose close blocks until released:

  • An SSE request whose body runs while the DELETE is held up closing that stream does not run its tool and writes nothing.
  • A request waiting on an elicitation when its session is terminated sees MCP::CancelledError with cancelled? true, and is recorded as cancelled with the reason "Session terminated".

Both fail against the previous library. Closing the streams before cancelling fails both; waking the waits before cancelling fails the second; dropping the wake-up hangs the existing "send_request unblocks when session is cleaned up" test. bundle exec rake test, bundle exec rake rubocop and bundle exec rake conformance:test (baseline) pass locally on Ruby 4.0.9.

Breaking Changes

None. The on_cancel hooks of a terminated session's requests now run before its streams are closed rather than after, so a hook that blocks now delays the closes instead of the other way round.

Types of changes

  • Bug fix (non-breaking change which fixes an issue)
  • New feature (non-breaking change which adds functionality)
  • Breaking change (fix or feature that would cause existing functionality to change)
  • Documentation update

Checklist

  • I have read the MCP Documentation
  • 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 (none needed: the Cancellation page already states both guarantees; this makes them hold while a stream is slow to close)

Additional context

The ordering trade-off is the one in Breaking Changes: a blocking on_cancel hook can now hold up the stream closes. I preferred that to the opposite, since a stalled close used to leave requests of an ended session running. The two parts can be split if you prefer: cancelling before the closes fixes (a), and waking the waits after the cancellation fixes (b).

## Motivation and Context

When the Streamable HTTP transport removes a session, `cleanup_session_unsafe` wakes the threads waiting on the
session's server-to-client requests with `:session_closed`, and `release_session` then closes the session's GET and
POST streams before it cancels the session's requests. A close can block for up to `stream_write_timeout:` (10 seconds
by default) on a stalled peer, and the cancellation waits behind it. Two documented guarantees of the Cancellation page
fail meanwhile:

- A request that reaches the session as it ends (modelcontextprotocol#698) is admitted and run: its tool runs with
  `server_context.cancelled?` false, and over SSE its result is written to its POST stream after the `DELETE`.
- A request waiting on a nested server-to-client request is woken with `:session_closed` before its own token is
  cancelled: the nested call raises "SSE session closed while waiting", the handler sees `cancelled?` false, and the
  request is recorded as an internal error instead of a cancellation. The wake-up runs first even without a stalled
  stream, so this outcome depends on thread scheduling.

`release_session` now cancels the session's requests first, then wakes the remaining waits with `:session_closed`, then
closes the streams. `cleanup_session_unsafe` collects the waits under the lock instead of waking them; no wait is added
for a session once it is removed. A nested request is now woken through its parent's cancellation hook, so it raises
`MCP::CancelledError` as it does for `notifications/cancelled`. Cancellations still run outside `@mutex`.

## How Has This Been Tested?

New tests in `test/mcp/server/transports/streamable_http_transport_test.rb`, with a GET stream whose close blocks until
released: an SSE request whose body runs while the `DELETE` is held up closing that stream does not run its tool and
writes nothing; a request waiting on an elicitation when its session is terminated sees `MCP::CancelledError` with
`cancelled?` true and is recorded as cancelled with the reason "Session terminated". Both fail against the previous
library. Closing the streams before cancelling fails both, waking the waits before cancelling fails the second, and
dropping the wake-up hangs the existing "send_request unblocks when session is cleaned up" test.

## Breaking Changes

None. `on_cancel` hooks of a terminated session's requests now run before its streams are closed rather than after.

Fixes modelcontextprotocol#708.

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

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

A terminated session's requests run or fail uncancelled while its streams close

1 participant