model-context-protocol-rb 0.5.1 → 0.7.0

data/lib/model_context_protocol/server/streamable_http_configuration.rb

@@ -0,0 +1,218 @@
+require "uri"
+
+module ModelContextProtocol
+  # Settings for servers that communicate via the MCP streamable HTTP transport, typically
+  # used by Rack applications serving multiple clients concurrently with Redis-backed coordination.
+  #
+  # Created by Server.with_streamable_http_transport, which yields an instance to a configuration
+  # block before passing it to Router. Adds session management (require_sessions), CORS control
+  # (validate_origin, allowed_origins), connection timeouts (session_ttl, ping_timeout), and
+  # Redis connection pool settings (redis_url, redis_pool_size, etc.) on top of the base class.
+  # validate_transport! verifies that redis_url is a valid Redis URL, and setup_transport!
+  # configures the Redis connection pool via RedisConfig before the server starts.
+  #
+  # Router queries supports_list_changed? (true for this subclass, false for stdio) to advertise
+  # listChanged capabilities in the initialize response. StreamableHttpTransport reads require_sessions,
+  # validate_origin, allowed_origins, session_ttl, and ping_timeout directly from this configuration.
+  class Server::StreamableHttpConfiguration < Server::Configuration
+    # @return [Symbol] :streamable_http (used by Server.start to instantiate StreamableHttpTransport)
+    def transport_type = :streamable_http
+
+    # @return [Boolean] true (Router advertises listChanged in initialize response capabilities;
+    #   StreamableHttpTransport can push unsolicited notifications to clients)
+    def supports_list_changed? = true
+
+    # @!attribute [w] require_sessions
+    #   Whether to enforce that clients send a session ID with each request.
+    #   StreamableHttpTransport checks this and returns 400 Bad Request if session_id is missing.
+    #   @see StreamableHttpTransport#handle
+    attr_writer :require_sessions
+
+    # @!attribute [w] validate_origin
+    #   Whether to enforce CORS origin validation against allowed_origins.
+    #   StreamableHttpTransport checks this in the OPTIONS preflight handler.
+    #   @see StreamableHttpTransport#handle
+    attr_writer :validate_origin
+
+    # @!attribute [w] allowed_origins
+    #   List of origins permitted in CORS requests; checked by StreamableHttpTransport
+    #   when validate_origin is true. Supports exact strings or "*" wildcard.
+    #   @see StreamableHttpTransport#handle
+    attr_writer :allowed_origins
+
+    # @!attribute [w] session_ttl
+    #   How long (in seconds) Redis session entries persist after last activity.
+    #   StreamableHttpTransport passes this to SessionStore.new to set key expiration.
+    #   @see StreamableHttpTransport#initialize
+    attr_writer :session_ttl
+
+    # @!attribute [w] ping_timeout
+    #   How long (in seconds) to wait for ping responses before considering a stream dead.
+    #   StreamableHttpTransport passes this to StreamMonitor to detect stale connections.
+    #   @see StreamableHttpTransport#initialize
+    attr_writer :ping_timeout
+
+    # @!attribute [w] redis_url
+    #   The Redis connection URL (redis:// or rediss:// scheme). Required.
+    #   Passed to RedisConfig during setup_transport! to create the connection pool.
+    attr_writer :redis_url
+
+    # @!attribute [w] redis_pool_size
+    #   Number of Redis connections in the pool.
+    #   Passed to RedisConfig during setup_transport!.
+    attr_writer :redis_pool_size
+
+    # @!attribute [w] redis_pool_timeout
+    #   Seconds to wait for a connection from the pool before raising.
+    #   Passed to RedisConfig during setup_transport!.
+    attr_writer :redis_pool_timeout
+
+    # @!attribute [w] redis_ssl_params
+    #   SSL parameters for Redis connections (e.g., { verify_mode: OpenSSL::SSL::VERIFY_NONE }).
+    #   Passed to RedisConfig during setup_transport!.
+    attr_writer :redis_ssl_params
+
+    # @!attribute [w] redis_enable_reaper
+    #   Whether to enable the idle connection reaper thread.
+    #   Passed to RedisConfig during setup_transport!.
+    attr_writer :redis_enable_reaper
+
+    # @!attribute [w] redis_reaper_interval
+    #   How often (in seconds) the reaper checks for idle connections.
+    #   Passed to RedisConfig during setup_transport!.
+    attr_writer :redis_reaper_interval
+
+    # @!attribute [w] redis_idle_timeout
+    #   How long (in seconds) a connection can sit idle before the reaper closes it.
+    #   Passed to RedisConfig during setup_transport!.
+    attr_writer :redis_idle_timeout
+
+    # Check whether session IDs are mandatory for incoming requests.
+    # StreamableHttpTransport reads this at request handling time to decide whether
+    # to reject requests without session_id query parameters.
+    #
+    # @return [Boolean] true by default (sessions are required)
+    def require_sessions
+      @require_sessions.nil? ? true : @require_sessions
+    end
+
+    # Check whether CORS origin validation is enforced.
+    # StreamableHttpTransport reads this during OPTIONS preflight handling to decide
+    # whether to reject requests with disallowed Origin headers.
+    #
+    # @return [Boolean] true by default (validate origins against allowed_origins list)
+    def validate_origin
+      @validate_origin.nil? ? true : @validate_origin
+    end
+
+    # Retrieve the list of permitted CORS origins.
+    # StreamableHttpTransport reads this during OPTIONS preflight handling to check
+    # the request's Origin header against allowed values.
+    #
+    # @return [Array<String>] list of allowed origins (localhost on standard ports by default);
+    #   supports exact matches or "*" for any origin
+    def allowed_origins
+      @allowed_origins || DEFAULT_ALLOWED_ORIGINS
+    end
+
+    # Retrieve the session expiration time in seconds.
+    # StreamableHttpTransport passes this to SessionStore.new, which sets Redis key TTLs
+    # to automatically expire inactive sessions.
+    #
+    # @return [Integer] seconds until session data expires (3600 = 1 hour by default)
+    def session_ttl
+      @session_ttl || 3600
+    end
+
+    # Retrieve the ping response timeout in seconds.
+    # StreamableHttpTransport passes this to StreamMonitor, which closes streams that
+    # don't respond to ping messages within this window (indicating client disconnection
+    # or network failure).
+    #
+    # @return [Integer] seconds to wait for ping responses (10 seconds by default)
+    def ping_timeout
+      @ping_timeout || 10
+    end
+
+    # @return [String, nil] the Redis connection URL
+    attr_reader :redis_url
+
+    # @return [Integer] number of Redis connections in the pool (default: 20)
+    def redis_pool_size
+      @redis_pool_size || 20
+    end
+
+    # @return [Integer] seconds to wait for a pool connection (default: 5)
+    def redis_pool_timeout
+      @redis_pool_timeout || 5
+    end
+
+    # @return [Hash, nil] SSL parameters for Redis connections
+    attr_reader :redis_ssl_params
+
+    # @return [Boolean] whether the idle connection reaper is enabled (default: true)
+    def redis_enable_reaper
+      @redis_enable_reaper.nil? ? true : @redis_enable_reaper
+    end
+
+    # @return [Integer] seconds between reaper checks (default: 60)
+    def redis_reaper_interval
+      @redis_reaper_interval || 60
+    end
+
+    # @return [Integer] seconds before idle connections are reaped (default: 300)
+    def redis_idle_timeout
+      @redis_idle_timeout || 300
+    end
+
+    private
+
+    # Default CORS origins permitted for HTTP transport: localhost and 127.0.0.1 on both HTTP and HTTPS.
+    # StreamableHttpTransport uses this list when allowed_origins hasn't been explicitly set,
+    # allowing development and testing without additional configuration. Production deployments
+    # should override with actual client origins or ["*"] for unrestricted access.
+    #
+    # @return [Array<String>] four localhost variants with http/https and localhost/127.0.0.1
+    DEFAULT_ALLOWED_ORIGINS = [
+      "http://localhost", "https://localhost",
+      "http://127.0.0.1", "https://127.0.0.1"
+    ].freeze
+
+    # Verify that redis_url is a valid Redis URL before allowing HTTP transport.
+    # Overrides the base class template method; called by validate! after checking name/version/registry.
+    # Uses URI parsing ("parse, don't validate") to catch nil, empty, malformed, and non-Redis URLs.
+    #
+    # @raise [InvalidTransportError] if redis_url is nil, empty, malformed, or not a redis:// / rediss:// URL
+    # @return [void]
+    def validate_transport!
+      uri = URI.parse(redis_url.to_s)
+      unless %w[redis rediss].include?(uri.scheme)
+        raise InvalidTransportError,
+          "streamable_http transport requires a valid Redis URL (redis:// or rediss://). " \
+          "Set config.redis_url in the configuration block."
+      end
+    rescue URI::InvalidURIError
+      raise InvalidTransportError,
+        "streamable_http transport requires a valid Redis URL (redis:// or rediss://). " \
+        "Set config.redis_url in the configuration block."
+    end
+
+    # Configure the Redis connection pool via RedisConfig.
+    # Overrides the base class template method; called by Server.build_server after validate! passes.
+    # Maps the redis_* attributes on this configuration to the corresponding RedisConfig::Configuration
+    # attributes, then starts the pool manager.
+    #
+    # @return [void]
+    def setup_transport!
+      ModelContextProtocol::Server::RedisConfig.configure do |redis_config|
+        redis_config.redis_url = redis_url
+        redis_config.pool_size = redis_pool_size
+        redis_config.pool_timeout = redis_pool_timeout
+        redis_config.enable_reaper = redis_enable_reaper
+        redis_config.reaper_interval = redis_reaper_interval
+        redis_config.idle_timeout = redis_idle_timeout
+        redis_config.ssl_params = redis_ssl_params
+      end
+    end
+  end
+end

data/lib/model_context_protocol/server/streamable_http_transport/event_counter.rb

@@ -17,19 +17,6 @@ module ModelContextProtocol
         count = @redis.incr(@counter_key)
         "#{@server_instance}-#{count}"
       end
-
-      def current_count
-        count = @redis.get(@counter_key)
-        count ? count.to_i : 0
-      end
-
-      def reset
-        @redis.set(@counter_key, 0)
-      end
-
-      def set_count(value)
-        @redis.set(@counter_key, value.to_i)
-      end
     end
   end
 end

data/lib/model_context_protocol/server/streamable_http_transport/message_poller.rb

@@ -6,10 +6,10 @@ module ModelContextProtocol
       POLL_INTERVAL = 0.1  # 100ms
       BATCH_SIZE = 100
 
-      def initialize(redis_client, stream_registry, logger, &message_delivery_block)
+      def initialize(redis_client, stream_registry, client_logger, &message_delivery_block)
         @redis = redis_client
         @stream_registry = stream_registry
-        @logger = logger
+        @client_logger = client_logger
         @message_delivery_block = message_delivery_block
         @running = false
         @poll_thread = nil
@@ -22,14 +22,14 @@ module ModelContextProtocol
         @poll_thread = Thread.new do
           poll_loop
         rescue => e
-          @logger.error("Message poller thread error", error: e.message, backtrace: e.backtrace.first(5))
+          @client_logger.error("Message poller thread error", error: e.message, backtrace: e.backtrace.first(5))
           sleep 1
           retry if @running
         end
 
         @poll_thread.name = "MCP-MessagePoller" if @poll_thread.respond_to?(:name=)
 
-        @logger.debug("Message poller started")
+        @client_logger.debug("Message poller started")
       end
 
       def stop
@@ -37,11 +37,11 @@ module ModelContextProtocol
 
         if @poll_thread&.alive?
           @poll_thread.kill
-          @poll_thread.join(timeout: 5)
+          @poll_thread.join(5)
         end
 
         @poll_thread = nil
-        @logger.debug("Message poller stopped")
+        @client_logger.debug("Message poller stopped")
       end
 
       def running?
@@ -55,7 +55,7 @@ module ModelContextProtocol
           begin
             poll_and_deliver_messages
           rescue => e
-            @logger.error("Error in message polling", error: e.message)
+            @client_logger.error("Error in message polling", error: e.message)
           end
 
           sleep POLL_INTERVAL
@@ -91,9 +91,9 @@ module ModelContextProtocol
         @message_delivery_block&.call(stream, message)
       rescue IOError, Errno::EPIPE, Errno::ECONNRESET
         @stream_registry.unregister_stream(session_id)
-        @logger.debug("Unregistered disconnected stream", session_id: session_id)
+        @client_logger.debug("Unregistered disconnected stream", session_id: session_id)
       rescue => e
-        @logger.error("Error delivering message to stream",
+        @client_logger.error("Error delivering message to stream",
           session_id: session_id, error: e.message)
       end
     end

data/lib/model_context_protocol/server/streamable_http_transport/notification_queue.rb

@@ -22,13 +22,6 @@ module ModelContextProtocol
         end
       end
 
-      def pop
-        notification_json = @redis.rpop(@queue_key)
-        return nil unless notification_json
-
-        JSON.parse(notification_json)
-      end
-
       def pop_all
         notification_jsons = @redis.multi do |multi|
           multi.lrange(@queue_key, 0, -1)
@@ -41,40 +34,6 @@ module ModelContextProtocol
           JSON.parse(notification_json)
         end
       end
-
-      def peek_all
-        notification_jsons = @redis.lrange(@queue_key, 0, -1)
-        return [] if notification_jsons.empty?
-
-        notification_jsons.reverse.map do |notification_json|
-          JSON.parse(notification_json)
-        end
-      end
-
-      def size
-        @redis.llen(@queue_key)
-      end
-
-      def empty?
-        size == 0
-      end
-
-      def clear
-        @redis.del(@queue_key)
-      end
-
-      def push_bulk(notifications)
-        return if notifications.empty?
-
-        notification_jsons = notifications.map(&:to_json)
-
-        @redis.multi do |multi|
-          notification_jsons.each do |json|
-            multi.lpush(@queue_key, json)
-          end
-          multi.ltrim(@queue_key, 0, @max_size - 1)
-        end
-      end
     end
   end
 end

data/lib/model_context_protocol/server/streamable_http_transport/request_store.rb

@@ -19,10 +19,10 @@ module ModelContextProtocol
 
       # Register a new request with its associated session
       #
-      # @param request_id [String] the unique request identifier
+      # @param jsonrpc_request_id [String] the unique JSON-RPC request identifier
       # @param session_id [String] the session identifier (can be nil for sessionless requests)
       # @return [void]
-      def register_request(request_id, session_id = nil)
+      def register_request(jsonrpc_request_id, session_id = nil)
         request_data = {
           session_id: session_id,
           server_instance: @server_instance,
@@ -30,11 +30,11 @@ module ModelContextProtocol
         }
 
         @redis.multi do |multi|
-          multi.set("#{REQUEST_KEY_PREFIX}#{request_id}",
+          multi.set("#{REQUEST_KEY_PREFIX}#{jsonrpc_request_id}",
             request_data.to_json, ex: @ttl)
 
           if session_id
-            multi.set("#{SESSION_KEY_PREFIX}#{session_id}:#{request_id}",
+            multi.set("#{SESSION_KEY_PREFIX}#{session_id}:#{jsonrpc_request_id}",
               true, ex: @ttl)
           end
         end
@@ -42,48 +42,37 @@ module ModelContextProtocol
 
       # Mark a request as cancelled
       #
-      # @param request_id [String] the unique request identifier
+      # @param jsonrpc_request_id [String] the unique JSON-RPC request identifier
       # @param reason [String] optional reason for cancellation
       # @return [Boolean] true if cancellation was recorded
-      def mark_cancelled(request_id, reason = nil)
+      def mark_cancelled(jsonrpc_request_id, reason = nil)
         cancellation_data = {
           cancelled_at: Time.now.to_f,
           reason: reason
         }
 
-        result = @redis.set("#{CANCELLED_KEY_PREFIX}#{request_id}",
+        result = @redis.set("#{CANCELLED_KEY_PREFIX}#{jsonrpc_request_id}",
           cancellation_data.to_json, ex: @ttl)
         result == "OK"
       end
 
       # Check if a request has been cancelled
       #
-      # @param request_id [String] the unique request identifier
+      # @param jsonrpc_request_id [String] the unique JSON-RPC request identifier
       # @return [Boolean] true if the request is cancelled, false otherwise
-      def cancelled?(request_id)
-        @redis.exists("#{CANCELLED_KEY_PREFIX}#{request_id}") == 1
-      end
-
-      # Get cancellation information for a request
-      #
-      # @param request_id [String] the unique request identifier
-      # @return [Hash, nil] cancellation data or nil if not cancelled
-      def get_cancellation_info(request_id)
-        data = @redis.get("#{CANCELLED_KEY_PREFIX}#{request_id}")
-        data ? JSON.parse(data) : nil
-      rescue JSON::ParserError
-        nil
+      def cancelled?(jsonrpc_request_id)
+        @redis.exists("#{CANCELLED_KEY_PREFIX}#{jsonrpc_request_id}") == 1
       end
 
       # Unregister a request (typically called when request completes)
       #
-      # @param request_id [String] the unique request identifier
+      # @param jsonrpc_request_id [String] the unique JSON-RPC request identifier
       # @return [void]
-      def unregister_request(request_id)
-        request_data = @redis.get("#{REQUEST_KEY_PREFIX}#{request_id}")
+      def unregister_request(jsonrpc_request_id)
+        request_data = @redis.get("#{REQUEST_KEY_PREFIX}#{jsonrpc_request_id}")
 
-        keys_to_delete = ["#{REQUEST_KEY_PREFIX}#{request_id}",
-          "#{CANCELLED_KEY_PREFIX}#{request_id}"]
+        keys_to_delete = ["#{REQUEST_KEY_PREFIX}#{jsonrpc_request_id}",
+          "#{CANCELLED_KEY_PREFIX}#{jsonrpc_request_id}"]
 
         if request_data
           begin
@@ -91,7 +80,7 @@ module ModelContextProtocol
             session_id = data["session_id"]
 
             if session_id
-              keys_to_delete << "#{SESSION_KEY_PREFIX}#{session_id}:#{request_id}"
+              keys_to_delete << "#{SESSION_KEY_PREFIX}#{session_id}:#{jsonrpc_request_id}"
             end
           rescue JSON::ParserError
             nil
@@ -101,25 +90,6 @@ module ModelContextProtocol
         @redis.del(*keys_to_delete) unless keys_to_delete.empty?
       end
 
-      # Get information about a specific request
-      #
-      # @param request_id [String] the unique request identifier
-      # @return [Hash, nil] request information or nil if not found
-      def get_request(request_id)
-        data = @redis.get("#{REQUEST_KEY_PREFIX}#{request_id}")
-        data ? JSON.parse(data) : nil
-      rescue JSON::ParserError
-        nil
-      end
-
-      # Check if a request is currently active
-      #
-      # @param request_id [String] the unique request identifier
-      # @return [Boolean] true if the request is active, false otherwise
-      def active?(request_id)
-        @redis.exists("#{REQUEST_KEY_PREFIX}#{request_id}") == 1
-      end
-
       # Clean up all requests associated with a session
       # This is typically called when a session is terminated
       #
@@ -131,93 +101,20 @@ module ModelContextProtocol
         return [] if request_keys.empty?
 
         # Extract request IDs from the keys
-        request_ids = request_keys.map do |key|
+        jsonrpc_request_ids = request_keys.map do |key|
           key.sub("#{SESSION_KEY_PREFIX}#{session_id}:", "")
         end
 
         # Delete all related keys
         all_keys = []
-        request_ids.each do |request_id|
-          all_keys << "#{REQUEST_KEY_PREFIX}#{request_id}"
-          all_keys << "#{CANCELLED_KEY_PREFIX}#{request_id}"
+        jsonrpc_request_ids.each do |jsonrpc_request_id|
+          all_keys << "#{REQUEST_KEY_PREFIX}#{jsonrpc_request_id}"
+          all_keys << "#{CANCELLED_KEY_PREFIX}#{jsonrpc_request_id}"
         end
         all_keys.concat(request_keys)
 
         @redis.del(*all_keys) unless all_keys.empty?
-        request_ids
-      end
-
-      # Get all active request IDs for a specific session
-      #
-      # @param session_id [String] the session identifier
-      # @return [Array<String>] list of active request IDs for the session
-      def get_session_requests(session_id)
-        pattern = "#{SESSION_KEY_PREFIX}#{session_id}:*"
-        request_keys = @redis.keys(pattern)
-
-        request_keys.map do |key|
-          key.sub("#{SESSION_KEY_PREFIX}#{session_id}:", "")
-        end
-      end
-
-      # Get all active request IDs across all sessions
-      #
-      # @return [Array<String>] list of all active request IDs
-      def get_all_active_requests
-        pattern = "#{REQUEST_KEY_PREFIX}*"
-        request_keys = @redis.keys(pattern)
-
-        request_keys.map do |key|
-          key.sub(REQUEST_KEY_PREFIX, "")
-        end
-      end
-
-      # Clean up expired requests based on TTL
-      # This method can be called periodically to ensure cleanup
-      #
-      # @return [Integer] number of expired requests cleaned up
-      def cleanup_expired_requests
-        active_keys = @redis.keys("#{REQUEST_KEY_PREFIX}*")
-        expired_count = 0
-        key_exists_without_expiration = -1
-        key_does_not_exist = -2
-
-        active_keys.each do |key|
-          ttl = @redis.ttl(key)
-          if ttl == key_exists_without_expiration
-            @redis.expire(key, @ttl)
-          elsif ttl == key_does_not_exist
-            expired_count += 1
-          end
-        end
-
-        expired_count
-      end
-
-      # Refresh the TTL for an active request
-      #
-      # @param request_id [String] the unique request identifier
-      # @return [Boolean] true if TTL was refreshed, false if request doesn't exist
-      def refresh_request_ttl(request_id)
-        request_data = @redis.get("#{REQUEST_KEY_PREFIX}#{request_id}")
-        return false unless request_data
-
-        @redis.multi do |multi|
-          multi.expire("#{REQUEST_KEY_PREFIX}#{request_id}", @ttl)
-          multi.expire("#{CANCELLED_KEY_PREFIX}#{request_id}", @ttl)
-
-          begin
-            data = JSON.parse(request_data)
-            session_id = data["session_id"]
-            if session_id
-              multi.expire("#{SESSION_KEY_PREFIX}#{session_id}:#{request_id}", @ttl)
-            end
-          rescue JSON::ParserError
-            nil
-          end
-        end
-
-        true
+        jsonrpc_request_ids
       end
     end
   end