Support session expiry controls for StreamableHTTPTransport

[koic]

Motivation and Context

The MCP specification recommends expiring session IDs to reduce session hijacking risks: https://modelcontextprotocol.io/specification/latest/basic/security_best_practices#session-hijacking

Several other SDKs (Go, C#, PHP, Python) already implement session expiry controls, but the Ruby SDK did not. Sessions persisted indefinitely unless explicitly deleted or a stream error occurred, leaving abandoned sessions to accumulate in memory.

This adds a session_idle_timeout: option to StreamableHTTPTransport#initialize. When set, sessions that receive no HTTP requests for the specified duration (in seconds) are automatically expired. Expired sessions return 404 on subsequent requests (GET and POST), matching the MCP specification's behavior for terminated sessions. Each request resets the idle timer, so actively used sessions are not interrupted.

A background reaper thread periodically cleans up expired sessions to handle orphaned sessions that receive no further requests. The reaper only starts when session_idle_timeout is configured.

The default is nil (no expiry) for backward compatibility, consistent with the Python SDK's approach. The Python SDK recommends 1800 seconds (30 minutes) for most deployments: modelcontextprotocol/python-sdk#2022

Resolves #265.

How Has This Been Tested?

Added tests for session expiry, idle timeout reset, reaper thread lifecycle, input validation, and default behavior in streamable_http_transport_test.rb. All existing tests continue to pass.

Breaking Change

None. The default value of session_idle_timeout is nil, which preserves the existing behavior of sessions never expiring. The new last_active_at field in the internal session hash is not part of the public API. Existing code that instantiates StreamableHTTPTransport.new(server) or
StreamableHTTPTransport.new(server, stateless: true) continues to work without changes.

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

[atesgoral]

What happens to the mutex if the reaper thread had a lock on it and was busy reaping?

[koic]

As far as I could verify, In MRI Ruby, this should be safe. Ruby runs ensure clauses even when a thread is terminated via Thread#kill, and Mutex#synchronize releases the lock in its ensure path.

So if the reaper is killed while holding the mutex, the thread will unwind and the lock should be released as part of that process. As a result, close's @mutex.synchronize is not expected to deadlock due to the mutex being left locked by Thread#kill.

[atesgoral]

Thanks! LGTM!

[atesgoral]

LGTM! Left a question because I don't know how mutexes held by threads behave when the thread is killed while holding a mutex. If this is already safe, no further comments!

[koic]

@atesgoral Thanks for the review. It looks like the approval was dismissed when I resolved a previous conflict. Could you take another look when you have a moment?