vector_mcp 0.3.4 → 0.4.0

data/lib/vector_mcp/transport/sse.rb

@@ -1,377 +0,0 @@
-# frozen_string_literal: true
-
-require "json"
-require "securerandom"
-require "puma"
-require "rack"
-require "concurrent-ruby"
-
-require_relative "../errors"
-require_relative "../util"
-require_relative "../session"
-require_relative "sse_session_manager"
-require_relative "sse/client_connection"
-require_relative "sse/stream_manager"
-require_relative "sse/message_handler"
-require_relative "sse/puma_config"
-
-module VectorMCP
-  module Transport
-    # Implements the Model Context Protocol transport over HTTP using Server-Sent Events (SSE)
-    # for server-to-client messages and HTTP POST for client-to-server messages.
-    # This transport uses Puma as the HTTP server with Ruby threading for concurrency.
-    #
-    # It provides two main HTTP endpoints:
-    # 1.  SSE Endpoint (`<path_prefix>/sse`): Clients connect here via GET to establish an SSE stream.
-    #     The server sends an initial `event: endpoint` with a unique URL for the client to POST messages back.
-    #     Subsequent messages from the server (responses, notifications) are sent as `event: message`.
-    # 2.  Message Endpoint (`<path_prefix>/message`): Clients POST JSON-RPC messages here.
-    #     The `session_id` (obtained from the SSE endpoint event) must be included as a query parameter.
-    #     The server responds with a 202 Accepted and then sends the actual JSON-RPC response/error
-    #     asynchronously over the client's established SSE stream.
-    #
-    # @example Basic Usage with a Server
-    #   server = VectorMCP::Server.new("my-sse-server")
-    #   # ... register tools, resources, prompts ...
-    #   transport = VectorMCP::Transport::SSE.new(server, port: 8080)
-    #   server.run(transport: transport)
-    #
-    # @attr_reader logger [Logger] The logger instance, shared with the server.
-    # @attr_reader server [VectorMCP::Server] The server instance this transport is bound to.
-    # @attr_reader host [String] The hostname or IP address the server will bind to.
-    # @attr_reader port [Integer] The port number the server will listen on.
-    # @attr_reader path_prefix [String] The base URL path for MCP endpoints (e.g., "/mcp").
-    class SSE
-      attr_reader :logger, :server, :host, :port, :path_prefix, :session_manager
-
-      # Initializes a new SSE transport.
-      #
-      # @param server [VectorMCP::Server] The server instance that will handle messages.
-      # @param options [Hash] Configuration options for the transport.
-      # @option options [String] :host ("localhost") The hostname or IP to bind to.
-      # @option options [Integer] :port (8000) The port to listen on.
-      # @option options [String] :path_prefix ("/mcp") The base path for HTTP endpoints.
-      # @option options [Boolean] :disable_session_manager (false) **DEPRECATED**: Whether to disable secure session isolation.
-      #   When false (default), each client gets isolated sessions. When true, all clients share a global session (security risk).
-      def initialize(server, options = {})
-        @server = server
-        @logger = server.logger
-        @host = options[:host] || "localhost"
-        @port = options[:port] || 8000
-        prefix = options[:path_prefix] || "/mcp"
-        @path_prefix = prefix.start_with?("/") ? prefix : "/#{prefix}"
-        @path_prefix = @path_prefix.delete_suffix("/")
-        @sse_path = "#{@path_prefix}/sse"
-        @message_path = "#{@path_prefix}/message"
-
-        # Thread-safe client storage using concurrent-ruby (legacy approach)
-        @clients = Concurrent::Hash.new
-        @session = nil # Global session for this transport instance, initialized in run
-
-        # Initialize session manager for secure multi-client session isolation (default behavior)
-        # Legacy shared session behavior can be enabled with disable_session_manager: true (deprecated)
-        if options[:disable_session_manager]
-          logger.warn("[DEPRECATED] SSE shared session mode is deprecated and poses security risks in multi-client scenarios. " \
-                      "Consider removing disable_session_manager: true to use secure per-client sessions.")
-          @session_manager = nil
-        else
-          @session_manager = SseSessionManager.new(self)
-        end
-        @puma_server = nil
-        @running = false
-
-        logger.debug { "SSE Transport initialized with prefix: #{@path_prefix}, SSE path: #{@sse_path}, Message path: #{@message_path}" }
-      end
-
-      # Starts the SSE transport, creating a shared session and launching the Puma server.
-      # This method will block until the server is stopped (e.g., via SIGINT/SIGTERM).
-      #
-      # @return [void]
-      # @raise [StandardError] if there's a fatal error during server startup.
-      def run
-        logger.info("Starting server with Puma SSE transport on #{@host}:#{@port}")
-        # Only create shared session if explicitly using legacy mode (deprecated)
-        create_session unless @session_manager
-        start_puma_server
-      rescue StandardError => e
-        handle_fatal_error(e)
-      end
-
-      # --- Rack-compatible #call method ---
-
-      # Handles incoming HTTP requests. This is the entry point for the Rack application.
-      # It routes requests to the appropriate handler based on the path.
-      #
-      # @param env [Hash] The Rack environment hash.
-      # @return [Array(Integer, Hash, Object)] A standard Rack response triplet: [status, headers, body].
-      def call(env)
-        start_time = Time.now
-        path = env["PATH_INFO"]
-        http_method = env["REQUEST_METHOD"]
-        logger.info "Received #{http_method} request for #{path}"
-
-        status, headers, body = route_request(path, env)
-
-        log_response(http_method, path, start_time, status)
-        [status, headers, body]
-      rescue StandardError => e
-        handle_call_error(http_method, path, e)
-      end
-
-      # --- Public methods for Server to send notifications ---
-
-      # Sends a JSON-RPC notification to the first available client session.
-      # If no clients are connected, returns false.
-      #
-      # @param method [String] The method name of the notification.
-      # @param params [Hash, Array, nil] The parameters for the notification (optional).
-      # @return [Boolean] True if the message was sent successfully, false otherwise.
-      def send_notification(method, params = nil)
-        return false if @clients.empty?
-
-        # Send to first available client
-        first_client = @clients.values.first
-        return false unless first_client
-
-        message = { jsonrpc: "2.0", method: method }
-        message[:params] = params if params
-
-        StreamManager.enqueue_message(first_client, message)
-      end
-
-      # Sends a JSON-RPC notification to a specific client session via its SSE stream.
-      #
-      # @param session_id [String] The ID of the client session to send the notification to.
-      # @param method [String] The method name of the notification.
-      # @param params [Hash, Array, nil] The parameters for the notification (optional).
-      # @return [Boolean] True if the message was successfully enqueued, false otherwise (e.g., client not found).
-      def send_notification_to_session(session_id, method, params = nil)
-        message = { jsonrpc: "2.0", method: method }
-        message[:params] = params if params
-
-        client_conn = @clients[session_id]
-        return false unless client_conn
-
-        StreamManager.enqueue_message(client_conn, message)
-      end
-
-      # Broadcasts a JSON-RPC notification to all currently connected client sessions.
-      #
-      # @param method [String] The method name of the notification.
-      # @param params [Hash, Array, nil] The parameters for the notification (optional).
-      # @return [void]
-      def broadcast_notification(method, params = nil)
-        # Broadcasting notification to clients
-        message = { jsonrpc: "2.0", method: method }
-        message[:params] = params if params
-
-        @clients.each_value do |client_conn|
-          StreamManager.enqueue_message(client_conn, message)
-        end
-      end
-
-      # Provides compatibility for tests that expect a `build_rack_app` helper.
-      # Since the transport itself is a Rack app (defines `#call`), it returns `self`.
-      #
-      # @param session [VectorMCP::Session, nil] An optional session to persist for testing.
-      # @return [self] The transport instance itself.
-      def build_rack_app(session = nil)
-        @session = session if session
-        self
-      end
-
-      # Stops the transport and cleans up resources
-      def stop
-        @running = false
-        if @session_manager
-          @session_manager.cleanup_all_sessions
-        else
-          cleanup_clients
-        end
-        @puma_server&.stop
-        logger.info("SSE transport stopped")
-      end
-
-      # Cleans up all client connections (legacy mode)
-      def cleanup_clients
-        logger.info("Cleaning up #{@clients.size} client connection(s)")
-        @clients.each_value do |client_conn|
-          client_conn.close if client_conn.respond_to?(:close)
-        rescue StandardError => e
-          logger.warn("Error closing client connection: #{e.message}")
-        end
-        @clients.clear
-      end
-
-      # --- Private methods ---
-      private
-
-      # Creates a single, shared {VectorMCP::Session} instance for this transport run.
-      # All client interactions will use this session context.
-      def create_session
-        @session = VectorMCP::Session.new(server, self, id: SecureRandom.uuid)
-      end
-
-      # Starts the Puma HTTP server.
-      def start_puma_server
-        @puma_server = Puma::Server.new(build_rack_app)
-        puma_config = PumaConfig.new(@host, @port, logger)
-        puma_config.configure(@puma_server)
-
-        @running = true
-        setup_signal_traps
-
-        logger.info("Puma server starting on #{@host}:#{@port}")
-        @puma_server.run.join # This blocks until server stops
-        logger.info("Puma server stopped.")
-      ensure
-        # Only cleanup if session manager is enabled
-        @session_manager&.cleanup_all_sessions
-        logger.info("SSE transport and resources shut down.")
-      end
-
-      # Sets up POSIX signal traps for graceful server shutdown (INT, TERM).
-      def setup_signal_traps
-        Signal.trap("INT") do
-          logger.info("SIGINT received, stopping server...")
-          stop
-        end
-        Signal.trap("TERM") do
-          logger.info("SIGTERM received, stopping server...")
-          stop
-        end
-      end
-
-      # Handles fatal errors during server startup or main run loop.
-      def handle_fatal_error(error)
-        logger.fatal("Fatal error in SSE transport: #{error.message}\n#{error.backtrace.join("\n")}")
-        exit(1)
-      end
-
-      # Routes an incoming request to the appropriate handler based on its path.
-      def route_request(path, env)
-        case path
-        when @sse_path
-          handle_sse_connection(env)
-        when @message_path
-          handle_message_post(env)
-        when "/"
-          [200, { "Content-Type" => "text/plain" }, ["VectorMCP Server OK"]]
-        else
-          [404, { "Content-Type" => "text/plain" }, ["Not Found"]]
-        end
-      end
-
-      # Logs the response details including status, method, path, and duration.
-      def log_response(method, path, start_time, status)
-        duration = format("%.4f", Time.now - start_time)
-        logger.info "Responded #{status} to #{method} #{path} in #{duration}s"
-      end
-
-      # Generic error handler for exceptions occurring within the `#call` method's request processing.
-      def handle_call_error(method, path, error)
-        error_context = method || "UNKNOWN_METHOD"
-        path_context = path || "UNKNOWN_PATH"
-        backtrace = error.backtrace.join("\n")
-        logger.error("Error during SSE request processing for #{error_context} #{path_context}: #{error.message}\n#{backtrace}")
-        [500, { "Content-Type" => "text/plain", "connection" => "close" }, ["Internal Server Error"]]
-      end
-
-      # Handles a new client connection to the SSE endpoint.
-      def handle_sse_connection(env)
-        return invalid_method_response(env) unless env["REQUEST_METHOD"] == "GET"
-
-        session_id = SecureRandom.uuid
-        logger.info("New SSE client connected: #{session_id}")
-
-        # Create client connection
-        client_conn = ClientConnection.new(session_id, logger)
-
-        # Store client connection
-        if @session_manager
-          @session_manager.register_client(session_id, client_conn)
-        else
-          @clients[session_id] = client_conn
-        end
-
-        # Build message POST URL for this client
-        message_post_url = build_post_url(session_id)
-        # Client message POST URL configured
-
-        # Set up SSE stream
-        headers = sse_headers
-        body = StreamManager.create_sse_stream(client_conn, message_post_url, logger)
-
-        [200, headers, body]
-      end
-
-      # Handles incoming POST requests containing JSON-RPC messages from clients.
-      def handle_message_post(env)
-        return invalid_post_method_response(env) unless env["REQUEST_METHOD"] == "POST"
-
-        session_id = extract_session_id(env["QUERY_STRING"])
-        unless session_id
-          return error_response(nil, VectorMCP::InvalidRequestError.new("Missing session_id parameter").code,
-                                "Missing session_id parameter")
-        end
-
-        # Get client connection and session
-        if @session_manager
-          client_conn = @session_manager.clients[session_id]
-          shared_session = @session_manager.shared_session
-        else
-          client_conn = @clients[session_id]
-          shared_session = @session
-        end
-
-        return error_response(nil, VectorMCP::NotFoundError.new("Invalid session_id").code, "Invalid session_id") unless client_conn
-
-        MessageHandler.new(@server, shared_session, logger).handle_post_message(env, client_conn)
-      end
-
-      # Helper methods
-      def invalid_method_response(env)
-        method = env["REQUEST_METHOD"]
-        logger.warn("Received non-GET request on SSE endpoint: #{method}")
-        [405, { "Content-Type" => "text/plain", "Allow" => "GET" }, ["Method Not Allowed. Only GET is supported for SSE endpoint."]]
-      end
-
-      def invalid_post_method_response(env)
-        method = env["REQUEST_METHOD"]
-        logger.warn("Received non-POST request on message endpoint: #{method}")
-        [405, { "Content-Type" => "text/plain", "Allow" => "POST" }, ["Method Not Allowed"]]
-      end
-
-      def sse_headers
-        {
-          "Content-Type" => "text/event-stream",
-          "Cache-Control" => "no-cache",
-          "Connection" => "keep-alive",
-          "X-Accel-Buffering" => "no"
-        }
-      end
-
-      def build_post_url(session_id)
-        "#{@message_path}?session_id=#{session_id}"
-      end
-
-      def extract_session_id(query_string)
-        return nil unless query_string
-
-        URI.decode_www_form(query_string).to_h["session_id"]
-      end
-
-      def error_response(id, code, message, data = nil)
-        status = case code
-                 when -32_700, -32_600, -32_602 then 400
-                 when -32_601, -32_001 then 404
-                 else 500
-                 end
-        error_payload = { code: code, message: message }
-        error_payload[:data] = data if data
-        body = { jsonrpc: "2.0", id: id, error: error_payload }.to_json
-        [status, { "Content-Type" => "application/json" }, [body]]
-      end
-    end
-  end
-end

data/lib/vector_mcp/transport/sse_session_manager.rb

@@ -1,188 +0,0 @@
-# frozen_string_literal: true
-
-require_relative "base_session_manager"
-
-module VectorMCP
-  module Transport
-    # Session manager for SSE transport with single shared session and client connection management.
-    # Extends BaseSessionManager with SSE-specific functionality.
-    #
-    # The SSE transport uses a single shared session for all client connections,
-    # but manages multiple client connections separately.
-    class SseSessionManager < BaseSessionManager
-      attr_reader :clients
-
-      # Initializes a new SSE session manager.
-      #
-      # @param transport [SSE] The parent transport instance
-      # @param session_timeout [Integer] Session timeout in seconds
-      def initialize(transport, session_timeout = 300)
-        @clients = Concurrent::Hash.new
-        super
-
-        # Create the single shared session for SSE transport
-        @shared_session = create_shared_session
-      end
-
-      # Gets the shared session for SSE transport.
-      # SSE uses a single session shared across all client connections.
-      #
-      # @return [Session] The shared session
-      def shared_session
-        @shared_session.touch!
-        @shared_session
-      end
-
-      # Registers a client connection with the session manager.
-      #
-      # @param client_id [String] The client connection ID
-      # @param client_connection [Object] The client connection object
-      # @return [void]
-      def register_client(client_id, client_connection)
-        @clients[client_id] = client_connection
-        session_metadata_updated?(@shared_session.id, clients_count: @clients.size)
-        logger.debug { "Client registered: #{client_id}" }
-      end
-
-      # Unregisters a client connection from the session manager.
-      #
-      # @param client_id [String] The client connection ID
-      # @return [Boolean] True if client was found and removed
-      def client_unregistered?(client_id)
-        client = @clients.delete(client_id)
-        return false unless client
-
-        session_metadata_updated?(@shared_session.id, clients_count: @clients.size)
-        logger.debug { "Client unregistered: #{client_id}" }
-        true
-      end
-
-      # Gets all client connections.
-      #
-      # @return [Hash] Hash of client_id => client_connection
-      def all_clients
-        @clients.dup
-      end
-
-      # Gets the number of connected clients.
-      #
-      # @return [Integer] Number of connected clients
-      def client_count
-        @clients.size
-      end
-
-      # Cleans up all clients and the shared session.
-      #
-      # @return [void]
-      def cleanup_all_sessions
-        logger.info { "Cleaning up #{@clients.size} client connection(s)" }
-
-        @clients.each_value do |client_conn|
-          close_client_connection(client_conn)
-        end
-        @clients.clear
-
-        super
-      end
-
-      protected
-
-      # Override: SSE doesn't need automatic cleanup since it has a single shared session.
-      def auto_cleanup_enabled?
-        false
-      end
-
-      # Override: Called when the shared session is terminated.
-      def on_session_terminated(_session)
-        # Clean up all client connections when session is terminated
-        @clients.each_value do |client_conn|
-          close_client_connection(client_conn)
-        end
-        @clients.clear
-      end
-
-      # Override: Returns metadata for SSE sessions.
-      def create_session_metadata
-        { clients_count: 0, session_type: :sse_shared }
-      end
-
-      # Override: Checks if any clients are connected to receive messages.
-      def can_send_message_to_session?(_session)
-        !@clients.empty?
-      end
-
-      # Override: Sends a message to the first available client.
-      def send_message_to_session(_session, message)
-        return false if @clients.empty?
-
-        first_client = @clients.values.first
-        return false unless first_client
-
-        @transport.class::StreamManager.enqueue_message(first_client, message)
-      end
-
-      # Override: Broadcasts messages to all connected clients.
-      def broadcast_message(message)
-        count = 0
-        @clients.each_value do |client_conn|
-          count += 1 if @transport.class::StreamManager.enqueue_message(client_conn, message)
-        end
-
-        logger.debug { "Message broadcasted to #{count} client(s)" }
-        count
-      end
-
-      private
-
-      # Creates the single shared session for SSE transport.
-      #
-      # @return [BaseSessionManager::Session] The shared session
-      def create_shared_session(rack_env = nil)
-        session_id = "sse_shared_session_#{SecureRandom.uuid}"
-        now = Time.now
-
-        # Create VectorMCP session context with request context
-        session_context = create_session_with_context(session_id, rack_env)
-
-        # Create internal session record using base session manager struct
-        session = BaseSessionManager::Session.new(
-          session_id,
-          session_context,
-          now,
-          now,
-          create_session_metadata
-        )
-
-        @sessions[session_id] = session
-        logger.info { "Shared SSE session created: #{session_id}" }
-        session
-      end
-
-      # Creates a VectorMCP::Session with proper request context from Rack environment
-      def create_session_with_context(session_id, rack_env)
-        request_context = if rack_env
-                            # Create request context from Rack environment
-                            VectorMCP::RequestContext.from_rack_env(rack_env, "sse")
-                          else
-                            # Fallback to minimal context for cases where rack_env is not available
-                            VectorMCP::RequestContext.minimal("sse")
-                          end
-        VectorMCP::Session.new(@transport.server, @transport, id: session_id, request_context: request_context)
-      end
-
-      # Closes a client connection safely.
-      #
-      # @param client_conn [Object] The client connection to close
-      # @return [void]
-      def close_client_connection(client_conn)
-        return unless client_conn
-
-        begin
-          client_conn.close if client_conn.respond_to?(:close)
-        rescue StandardError => e
-          logger.warn { "Error closing client connection: #{e.message}" }
-        end
-      end
-    end
-  end
-end