feat(service): add close() method for graceful connection shutdown

[TheMailmans]

Summary

This PR primarily fixes #572 by enabling graceful shutdown without consuming self. While implementing this, I noticed delete_session() is spawned as a background task, which means close() may return before HTTP session cleanup completes. Since this is part of the same shutdown lifecycle and can cause resource leaks/races, I'm including a small, localized fix to ensure cleanup is completed before close() returns. If maintainers prefer, I can split the cleanup timing change into a follow-up PR.

Changes

Service Layer (service.rs)

• close(&mut self) - Gracefully shuts down the connection and waits for cleanup to complete without consuming the RunningService. This was the main ask in Client connection is not closed on drop, and no way to gracefully stop #572.
• close_with_timeout(&mut self, Duration) - Same as close() but with a bounded wait time. Useful for apps that need deterministic shutdown.
• is_closed(&self) - Check if the service has already been closed or cancelled.
• Drop impl - Logs a debug message if dropped without explicit close() call. The DropGuard still handles async cleanup, but this helps developers catch missing cleanup calls.

HTTP Transport (streamable_http_client.rs)

• Moved delete_session() from a fire-and-forget tokio::spawn to inline cleanup at the end of the worker's run() method
• Added a 5-second timeout on the cleanup HTTP request to prevent close() from hanging indefinitely if the server is unresponsive
• This ensures the HTTP DELETE request completes (or times out) before close() returns, preventing orphaned sessions on authenticated MCP servers

Why both changes together?

The original issue mentions that "for authenticated MCP connections, the sessions on the remote would still be active." The service-layer close() method alone doesn't fully solve this because the HTTP transport's session deletion was spawned as a background task. By moving it inline with a timeout, close() now guarantees bounded, deterministic cleanup.

Design Decisions

Q: Can close() hang forever?
No. The HTTP session cleanup has a 5-second timeout. If the server doesn't respond, we log a warning and continue. close_with_timeout() provides an additional layer of control at the service level.

Q: What happens if cancelled mid-cleanup?
The cleanup runs after the main loop exits, so the cancellation token has already fired. The timeout ensures we don't block indefinitely regardless of server behavior.

Manual Verification

# Build
cargo check -p rmcp --all-features

# Run all tests
cargo test -p rmcp --all-features

# Run the new close() tests specifically  
cargo test --test test_close_connection --features "client server"

# Clippy
cargo clippy -p rmcp --all-features

All tests pass, clippy is clean.

Test Plan

• test_close_method - Verifies close() works and can be called twice safely
• test_close_with_timeout - Verifies timeout-bounded shutdown
• test_cancel_method - Confirms existing cancel() API still works (backward compat)
• test_drop_without_close - Verifies drop behavior doesn't panic and async cleanup still happens

Backward Compatibility

• Existing cancel() method still works (now delegates to close() internally)
• Existing waiting() method still works
• Dropping without close() still triggers cleanup via DropGuard - just with a debug log now

Fixes #572

[Ben-Lichtman]

This seems to be using "cancel" to implement close, should these be two separate things? ie. closing the underlying transport, instead of just always cancelling?

[TheMailmans]

Good point; conceptually, 'close' and 'cancel' represent different intents. close() is meant to be a graceful, deterministic shutdown that ensures the underlying transport is closed and remote session cleanup completes (with timeouts so it can’t hang). cancel() is more of an abort/interrupt.

In this PR, cancel() delegates to close() mainly to make the existing API safe by default and ensure authenticated sessions aren’t leaked (the core issue in #572). I’m happy to split the semantics more explicitly (e.g., graceful vs abort paths) if maintainers prefer keeping those behaviors distinct.

[Ben-Lichtman]

@scutuatua-crypto do you have any opinions on the unanswered questions raised here before the PR gets merged?

[jokemanfire]

Does this submission seem to address the issue of graceless exit due to the server not closing invalid connections when the client aborts unexpectedly?
It will cause the server can't exited graceful.

[Ben-Lichtman]

The solution given here technically does address the issue in a workable way yes, maybe it should be left to later / a different issue to nail down the details?

[alexhancock]

I'm fine with the change coupling the two concepts. Thanks