a97e391353
## Motivation and Context The MCP specification defines `notifications/cancelled` so either party can stop a previously-issued in-flight request. The Ruby SDK declared the method constant but had no receive logic, no in-flight tracking, and no way for handlers to participate in cancellation; cancellation notifications fell through to the unsupported-method path. This PR implements the **server-side** half of the spec. The server stops processing the targeted request cooperatively and suppresses its JSON-RPC response, matching the Python SDK's anyio `CancelScope` and the TypeScript SDK's `RequestHandlerExtra.signal`. Cancellation is observable by every user-overridable request handler: - `Tool.call` (tools/call) - prompt templates (prompts/get) - blocks registered via `resources_read_handler` / `completion_handler` / `resources_subscribe_handler` / `resources_unsubscribe_handler` / `define_custom_method` Each handler opts in by declaring a `server_context:` keyword and polls `server_context.cancelled?` or calls `server_context.raise_if_cancelled!` (raising `MCP::CancelledError`) inside long-running work. Handlers that keep their existing `|params|` (or `|args|`) signature continue to work unchanged. On `StreamableHTTPTransport`, cancelling a parent `tools/call` automatically cancels n ested server-to-client requests (`sampling/createMessage`, `elicitation/create`); the nested `send_request` raises `MCP::CancelledError` and a cancel notification is routed to the peer on the parent's POST response stream. `StdioTransport` is single-threaded and blocks on `$stdin.gets`, so it deliberately does not propagate nested cancellation. Tools running on stdio still observe cancellation between calls via `server_context.cancelled?`. The design is cooperative-only (no `Thread#raise`) because preemptive cancellation is unsafe across Rack adapters and arbitrary handler code. The `initialize` request is never cancellable, satisfying the spec rule that it MUST NOT be cancelled. Unknown / completed / duplicate cancel notifications are silently ignored per the spec. `MCP::Client#cancel` (an equivalent that aborts the calling thread's synchronous wait) is deferred to a follow-up PR. Ref: https://modelcontextprotocol.io/specification/2025-11-25/basic/utilities/cancellation ## How Has This Been Tested? `test/mcp/cancellation_test.rb` covers the `MCP::Cancellation` token contract. `test/mcp/server_cancellation_test.rb` covers end-to-end cancellation: - A handler spins on `cancelled?` in a background thread; the test sends `notifications/cancelled` and asserts the handler observed cancellation and the JSON-RPC response was suppressed. Each user-overridable handler type (tool, prompt template, resources/read, completion, custom method) has its own regression test. - `initialize` is not cancellable; unknown / duplicate / late-after-completion cancels are silently ignored. - The `reason` propagates into the `cancellation_reason` instrumentation field. - Custom transports implementing only the abstract `(method, params = nil)` contract keep working; the new kwargs (`session_id:`, `related_request_id:`, `parent_cancellation:`, `server_session:`) are silently dropped when the transport's signature does not declare them. `StreamableHTTPTransport` tests cover nested cancellation, hook deregistration after normal completion (so a late parent cancel does not emit a stray `notifications/cancelled`), and the first-writer-wins race when a real response and a cancel arrive concurrently. ## Breaking Change None. `MCP::ServerContext#initialize` gains an optional `cancellation:` keyword (defaults to `nil`), and `StreamableHTTPTransport#send_request` / `#send_notification` gain optional cancellation kwargs. The abstract `Transport` base class and `StdioTransport` keep their existing `(method, params = nil)` signatures, and custom transports following those signatures continue to work. `StreamableHTTPTransport` now dispatches client-originated notifications through `ServerSession#handle_json` before returning 202; previously these were accepted without dispatch, but the existing handlers for `notifications/initialized` and `notifications/progress` were already no-ops, so no user-visible effect is expected. Adding `server_context:` to a handler block is strictly opt-in.
66 lines
1.8 KiB
Ruby
66 lines
1.8 KiB
Ruby
# frozen_string_literal: true
|
|
|
|
require "test_helper"
|
|
|
|
module MCP
|
|
class CancellationTest < ActiveSupport::TestCase
|
|
test "starts not cancelled" do
|
|
cancellation = Cancellation.new
|
|
|
|
refute_predicate cancellation, :cancelled?
|
|
assert_nil cancellation.reason
|
|
end
|
|
|
|
test "#cancel flips state and stores reason" do
|
|
cancellation = Cancellation.new
|
|
|
|
assert cancellation.cancel(reason: "user requested")
|
|
assert_predicate cancellation, :cancelled?
|
|
assert_equal "user requested", cancellation.reason
|
|
end
|
|
|
|
test "#cancel is idempotent" do
|
|
cancellation = Cancellation.new
|
|
|
|
assert cancellation.cancel(reason: "first")
|
|
refute cancellation.cancel(reason: "second")
|
|
assert_equal "first", cancellation.reason
|
|
end
|
|
|
|
test "#on_cancel fires once on cancellation" do
|
|
cancellation = Cancellation.new
|
|
fired = []
|
|
|
|
cancellation.on_cancel { |reason| fired << reason }
|
|
cancellation.cancel(reason: "stop")
|
|
cancellation.cancel(reason: "again")
|
|
|
|
assert_equal ["stop"], fired
|
|
end
|
|
|
|
test "#on_cancel fires immediately when already cancelled" do
|
|
cancellation = Cancellation.new
|
|
cancellation.cancel(reason: "done")
|
|
fired = []
|
|
|
|
cancellation.on_cancel { |reason| fired << reason }
|
|
|
|
assert_equal ["done"], fired
|
|
end
|
|
|
|
test "#raise_if_cancelled! raises CancelledError when cancelled" do
|
|
cancellation = Cancellation.new(request_id: "req-1")
|
|
cancellation.cancel(reason: "abort")
|
|
|
|
error = assert_raises(CancelledError) { cancellation.raise_if_cancelled! }
|
|
assert_equal "req-1", error.request_id
|
|
assert_equal "abort", error.reason
|
|
end
|
|
|
|
test "#raise_if_cancelled! is a no-op when not cancelled" do
|
|
cancellation = Cancellation.new
|
|
|
|
assert_nil cancellation.raise_if_cancelled!
|
|
end
|
|
end
|
|
end
|