vector_mcp 0.3.2 → 0.3.4

data/lib/vector_mcp/transport/base_session_manager.rb

@@ -0,0 +1,320 @@
+# frozen_string_literal: true
+
+require "securerandom"
+require "concurrent-ruby"
+
+module VectorMCP
+  module Transport
+    # Base session manager providing unified session lifecycle management across all transports.
+    # This abstract base class defines the standard interface that all transport session managers
+    # should implement, ensuring consistent session handling regardless of transport type.
+    #
+    # @abstract Subclass and implement transport-specific methods
+    class BaseSessionManager
+      # Session data structure for unified session management
+      Session = Struct.new(:id, :context, :created_at, :last_accessed_at, :metadata) do
+        def touch!
+          self.last_accessed_at = Time.now
+        end
+
+        def expired?(timeout)
+          Time.now - last_accessed_at > timeout
+        end
+
+        def age
+          Time.now - created_at
+        end
+      end
+
+      attr_reader :transport, :session_timeout, :logger
+
+      # Initializes a new session manager.
+      #
+      # @param transport [Object] The parent transport instance
+      # @param session_timeout [Integer] Session timeout in seconds (default: 300)
+      def initialize(transport, session_timeout = 300)
+        @transport = transport
+        @session_timeout = session_timeout
+        @logger = transport.logger
+        @sessions = Concurrent::Hash.new
+        @cleanup_timer = nil
+
+        start_cleanup_timer if auto_cleanup_enabled?
+        logger.debug { "#{self.class.name} initialized with session_timeout: #{session_timeout}" }
+      end
+
+      # Gets an existing session by ID.
+      #
+      # @param session_id [String] The session ID
+      # @return [Session, nil] The session if found and valid
+      def get_session(session_id)
+        return nil unless session_id
+
+        session = @sessions[session_id]
+        return nil unless session && !session.expired?(@session_timeout)
+
+        session.touch!
+        session
+      end
+
+      # Gets an existing session or creates a new one.
+      #
+      # @param session_id [String, nil] The session ID (optional)
+      # @return [Session] The existing or newly created session
+      def get_or_create_session(session_id = nil)
+        if session_id
+          session = get_session(session_id)
+          return session if session
+
+          # If session_id was provided but not found, create with that ID
+          return create_session(session_id)
+        end
+
+        create_session
+      end
+
+      # Creates a new session.
+      #
+      # @param session_id [String, nil] Optional specific session ID to use
+      # @return [Session] The newly created session
+      def create_session(session_id = nil)
+        session_id ||= generate_session_id
+        now = Time.now
+
+        # Create VectorMCP session context
+        session_context = VectorMCP::Session.new(@transport.server, @transport, id: session_id)
+
+        # Create internal session record with transport-specific metadata
+        session = Session.new(
+          session_id,
+          session_context,
+          now,
+          now,
+          create_session_metadata
+        )
+
+        @sessions[session_id] = session
+
+        logger.info { "Session created: #{session_id}" }
+        on_session_created(session)
+        session
+      end
+
+      # Terminates a session by ID.
+      #
+      # @param session_id [String] The session ID to terminate
+      # @return [Boolean] True if session was found and terminated
+      def session_terminated?(session_id)
+        session = @sessions.delete(session_id)
+        return false unless session
+
+        on_session_terminated(session)
+        logger.info { "Session terminated: #{session_id}" }
+        true
+      end
+
+      # Gets the current number of active sessions.
+      #
+      # @return [Integer] Number of active sessions
+      def session_count
+        @sessions.size
+      end
+
+      # Gets all active session IDs.
+      #
+      # @return [Array<String>] Array of session IDs
+      def active_session_ids
+        @sessions.keys
+      end
+
+      # Checks if any sessions exist.
+      #
+      # @return [Boolean] True if at least one session exists
+      def sessions?
+        !@sessions.empty?
+      end
+
+      # Cleans up all sessions and stops the cleanup timer.
+      #
+      # @return [void]
+      def cleanup_all_sessions
+        logger.info { "Cleaning up all sessions: #{@sessions.size}" }
+
+        @sessions.each_value do |session|
+          on_session_terminated(session)
+        end
+
+        @sessions.clear
+        stop_cleanup_timer
+      end
+
+      # Updates session metadata.
+      #
+      # @param session_id [String] The session ID
+      # @param metadata [Hash] Metadata to merge
+      # @return [Boolean] True if session was found and updated
+      def session_metadata_updated?(session_id, metadata)
+        session = @sessions[session_id]
+        return false unless session
+
+        session.metadata.merge!(metadata)
+        session.touch!
+        true
+      end
+
+      # Gets session metadata.
+      #
+      # @param session_id [String] The session ID
+      # @return [Hash, nil] Session metadata or nil if session not found
+      def get_session_metadata(session_id)
+        session = @sessions[session_id]
+        session&.metadata
+      end
+
+      # Finds sessions matching criteria.
+      #
+      # @param criteria [Hash] Search criteria
+      # @option criteria [Symbol] :created_after Time to search after
+      # @option criteria [Symbol] :metadata Hash of metadata to match
+      # @return [Array<Session>] Matching sessions
+      def find_sessions(criteria = {})
+        @sessions.values.select do |session|
+          matches_criteria?(session, criteria)
+        end
+      end
+
+      # Broadcasts a message to all sessions that support messaging.
+      #
+      # @param message [Hash] The message to broadcast
+      # @return [Integer] Number of sessions the message was sent to
+      def broadcast_message(message)
+        count = 0
+        @sessions.each_value do |session|
+          next unless can_send_message_to_session?(session)
+
+          count += 1 if message_sent_to_session?(session, message)
+        end
+
+        # Message broadcasted to recipients
+        count
+      end
+
+      protected
+
+      # Hook called when a session is created. Override in subclasses for transport-specific logic.
+      #
+      # @param session [Session] The newly created session
+      # @return [void]
+      def on_session_created(session)
+        # Override in subclasses
+      end
+
+      # Hook called when a session is terminated. Override in subclasses for transport-specific cleanup.
+      #
+      # @param session [Session] The session being terminated
+      # @return [void]
+      def on_session_terminated(session)
+        # Override in subclasses
+      end
+
+      # Creates transport-specific session metadata. Override in subclasses.
+      #
+      # @return [Hash] Initial metadata for the session
+      def create_session_metadata
+        {}
+      end
+
+      # Determines if this session manager should enable automatic cleanup.
+      # Override in subclasses that don't need automatic cleanup (e.g., stdio with single session).
+      #
+      # @return [Boolean] True if auto-cleanup should be enabled
+      def auto_cleanup_enabled?
+        true
+      end
+
+      # Checks if a message can be sent to the given session.
+      # Override in subclasses based on transport capabilities.
+      #
+      # @param session [Session] The session to check
+      # @return [Boolean] True if messaging is supported for this session
+      def can_send_message_to_session?(_session)
+        false # Override in subclasses
+      end
+
+      # Sends a message to a specific session.
+      # Override in subclasses based on transport messaging mechanism.
+      #
+      # @param session [Session] The target session
+      # @param message [Hash] The message to send
+      # @return [Boolean] True if message was sent successfully
+      def message_sent_to_session?(_session, _message)
+        false # Override in subclasses
+      end
+
+      private
+
+      # Generates a cryptographically secure session ID.
+      #
+      # @return [String] A unique session ID
+      def generate_session_id
+        SecureRandom.uuid
+      end
+
+      # Starts the automatic cleanup timer if auto-cleanup is enabled.
+      #
+      # @return [void]
+      def start_cleanup_timer
+        return unless auto_cleanup_enabled?
+
+        # Run cleanup every 60 seconds
+        @cleanup_timer = Concurrent::TimerTask.new(execution_interval: 60) do
+          cleanup_expired_sessions
+        end
+        @cleanup_timer.execute
+      end
+
+      # Stops the automatic cleanup timer.
+      #
+      # @return [void]
+      def stop_cleanup_timer
+        @cleanup_timer&.shutdown
+        @cleanup_timer = nil
+      end
+
+      # Cleans up expired sessions.
+      #
+      # @return [void]
+      def cleanup_expired_sessions
+        expired_sessions = []
+
+        @sessions.each do |session_id, session|
+          expired_sessions << session_id if session.expired?(@session_timeout)
+        end
+
+        expired_sessions.each do |session_id|
+          session = @sessions.delete(session_id)
+          on_session_terminated(session) if session
+        end
+
+        return unless expired_sessions.any?
+
+        logger.debug { "Cleaned up expired sessions: #{expired_sessions.size}" }
+      end
+
+      # Checks if a session matches the given criteria.
+      #
+      # @param session [Session] The session to check
+      # @param criteria [Hash] The search criteria
+      # @return [Boolean] True if session matches all criteria
+      def matches_criteria?(session, criteria)
+        return false if criteria[:created_after] && session.created_at <= criteria[:created_after]
+
+        criteria[:metadata]&.each do |key, value|
+          return false unless session.metadata[key] == value
+        end
+
+        true
+      end
+    end
+  end
+end

data/lib/vector_mcp/transport/http_stream/event_store.rb

@@ -0,0 +1,157 @@
+# frozen_string_literal: true
+
+require "concurrent-ruby"
+require "securerandom"
+
+module VectorMCP
+  module Transport
+    class HttpStream
+      # Manages Server-Sent Events storage for resumable connections.
+      #
+      # Handles:
+      # - Event storage with unique IDs
+      # - Event replay from a specific Last-Event-ID
+      # - Circular buffer for memory efficiency
+      # - Thread-safe operations
+      #
+      # @api private
+      class EventStore
+        # Event data structure
+        Event = Struct.new(:id, :data, :type, :timestamp, :session_id) do
+          def to_sse_format
+            lines = []
+            lines << "id: #{id}"
+            lines << "event: #{type}" if type
+            lines << "data: #{data}"
+            lines << ""
+            lines.join("\n")
+          end
+        end
+
+        attr_reader :max_events, :logger
+
+        # Initializes a new event store.
+        #
+        # @param max_events [Integer] Maximum number of events to retain
+        def initialize(max_events)
+          @max_events = max_events
+          @events = Concurrent::Array.new
+          @event_index = Concurrent::Hash.new # event_id -> index for fast lookup
+          @current_sequence = Concurrent::AtomicFixnum.new(0)
+        end
+
+        # Stores a new event and returns its ID.
+        #
+        # @param data [String] The event data
+        # @param type [String] The event type (optional)
+        # @param session_id [String, nil] The session ID to scope this event to
+        # @return [String] The generated event ID
+        def store_event(data, type = nil, session_id: nil)
+          event_id = generate_event_id
+          timestamp = Time.now
+
+          event = Event.new(event_id, data, type, timestamp, session_id)
+
+          # Add to events array
+          @events.push(event)
+
+          # Update index
+          @event_index[event_id] = @events.length - 1
+
+          # Maintain circular buffer
+          if @events.length > @max_events
+            removed_event = @events.shift
+            @event_index.delete(removed_event.id)
+
+            # Update all indices after removal
+            @event_index.transform_values! { |index| index - 1 }
+          end
+
+          event_id
+        end
+
+        # Retrieves events starting from a specific event ID, optionally filtered by session.
+        #
+        # @param last_event_id [String] The last event ID received by client
+        # @param session_id [String, nil] Filter events to this session only
+        # @return [Array<Event>] Array of events after the specified ID
+        def get_events_after(last_event_id, session_id: nil)
+          events = if last_event_id.nil?
+                     @events.to_a
+                   else
+                     last_index = @event_index[last_event_id]
+                     return [] if last_index.nil?
+
+                     start_index = last_index + 1
+                     return [] if start_index >= @events.length
+
+                     @events[start_index..]
+                   end
+
+          events = events.select { |e| e.session_id == session_id } if session_id
+          events
+        end
+
+        # Gets the total number of stored events.
+        #
+        # @return [Integer] Number of events currently stored
+        def event_count
+          @events.length
+        end
+
+        # Gets the oldest event ID (for debugging/monitoring).
+        #
+        # @return [String, nil] The oldest event ID or nil if no events
+        def oldest_event_id
+          @events.first&.id
+        end
+
+        # Gets the newest event ID (for debugging/monitoring).
+        #
+        # @return [String, nil] The newest event ID or nil if no events
+        def newest_event_id
+          @events.last&.id
+        end
+
+        # Checks if an event ID exists in the store.
+        #
+        # @param event_id [String] The event ID to check
+        # @return [Boolean] True if event exists
+        def event_exists?(event_id)
+          @event_index.key?(event_id)
+        end
+
+        # Clears all stored events.
+        #
+        # @return [void]
+        def clear
+          @events.clear
+          @event_index.clear
+        end
+
+        # Gets statistics about the event store.
+        #
+        # @return [Hash] Statistics hash
+        def stats
+          {
+            total_events: event_count,
+            max_events: @max_events,
+            oldest_event_id: oldest_event_id,
+            newest_event_id: newest_event_id,
+            memory_usage_ratio: event_count.to_f / @max_events
+          }
+        end
+
+        private
+
+        # Generates a unique event ID.
+        #
+        # @return [String] A unique event ID
+        def generate_event_id
+          sequence = @current_sequence.increment
+          "#{Time.now.to_i}-#{sequence}-#{SecureRandom.hex(4)}"
+        end
+      end
+    end
+  end
+end

data/lib/vector_mcp/transport/http_stream/session_manager.rb

@@ -0,0 +1,191 @@
+# frozen_string_literal: true
+
+require "securerandom"
+require "concurrent-ruby"
+require_relative "../base_session_manager"
+
+module VectorMCP
+  module Transport
+    class HttpStream
+      # Manages HTTP stream sessions with automatic cleanup and thread safety.
+      # Extends BaseSessionManager with HTTP streaming-specific functionality.
+      #
+      # Handles:
+      # - Session creation and lifecycle management
+      # - Thread-safe session storage using concurrent-ruby
+      # - Automatic session cleanup based on timeout
+      # - Session context integration with VectorMCP::Session
+      # - HTTP streaming connection management
+      #
+      # @api private
+      class SessionManager < BaseSessionManager
+        # HTTP stream session data structure extending base session
+        Session = Struct.new(:id, :context, :created_at, :last_accessed_at, :metadata) do
+          def touch!
+            self.last_accessed_at = Time.now
+          end
+
+          def expired?(timeout)
+            Time.now - last_accessed_at > timeout
+          end
+
+          def age
+            Time.now - created_at
+          end
+
+          def streaming?
+            metadata[:streaming_connection] && !metadata[:streaming_connection].nil?
+          end
+
+          def streaming_connection
+            metadata[:streaming_connection]
+          end
+
+          def streaming_connection=(connection)
+            metadata[:streaming_connection] = connection
+          end
+        end
+
+        # Initializes a new HTTP stream session manager.
+        #
+        # @param transport [HttpStream] The parent transport instance
+        # @param session_timeout [Integer] Session timeout in seconds
+
+        # Optimized session creation with reduced object allocation and faster context creation
+        def create_session(session_id = nil, rack_env = nil)
+          session_id ||= generate_session_id
+          now = Time.now
+
+          # Optimize session context creation - use cached minimal context when rack_env is nil
+          session_context = if rack_env
+                              create_session_with_context(session_id, rack_env)
+                            else
+                              create_minimal_session_context(session_id)
+                            end
+
+          # Pre-allocate metadata hash for better performance
+          metadata = { streaming_connection: nil }
+
+          # Create internal session record with streaming connection metadata
+          session = Session.new(session_id, session_context, now, now, metadata)
+
+          @sessions[session_id] = session
+
+          logger.info { "Session created: #{session_id}" }
+          session
+        end
+
+        # Override to add rack_env support.
+        # Returns nil when a session_id is provided but not found (expired or unknown).
+        # Callers are responsible for returning 404 in that case.
+        def get_or_create_session(session_id = nil, rack_env = nil)
+          if session_id
+            session = get_session(session_id)
+            if session
+              # Update existing session context if rack_env is provided
+              if rack_env
+                request_context = VectorMCP::RequestContext.from_rack_env(rack_env, "http_stream")
+                session.context.request_context = request_context
+              end
+              return session
+            end
+
+            # Session ID provided but not found — signal 404 to caller
+            return nil
+          end
+
+          create_session(nil, rack_env)
+        end
+
+        # Creates a VectorMCP::Session with proper request context from Rack environment
+        def create_session_with_context(session_id, rack_env)
+          request_context = VectorMCP::RequestContext.from_rack_env(rack_env, "http_stream")
+          VectorMCP::Session.new(@transport.server, @transport, id: session_id, request_context: request_context)
+        end
+
+        # Creates a minimal session context for each session (no caching to prevent contamination)
+        def create_minimal_session_context(session_id)
+          # Create a new minimal context for each session to prevent cross-session contamination
+          minimal_context = VectorMCP::RequestContext.minimal("http_stream")
+          VectorMCP::Session.new(@transport.server, @transport, id: session_id, request_context: minimal_context)
+        end
+
+        # Terminates a session by ID.
+        #
+        # @param session_id [String] The session ID to terminate
+        # @return [Boolean] True if session was found and terminated
+        # rubocop:disable Naming/PredicateMethod
+        def terminate_session(session_id)
+          session = @sessions.delete(session_id)
+          return false unless session
+
+          on_session_terminated(session)
+          logger.info { "Session terminated: #{session_id}" }
+          true
+        end
+        # rubocop:enable Naming/PredicateMethod
+
+        # Associates a streaming connection with a session.
+        #
+        # @param session [Session] The session to associate with
+        # @param connection [Object] The streaming connection object
+        # @return [void]
+        def set_streaming_connection(session, connection)
+          session.streaming_connection = connection
+          session.touch!
+          logger.debug { "Streaming connection associated: #{session.id}" }
+        end
+
+        # Removes streaming connection from a session.
+        #
+        # @param session [Session] The session to remove streaming from
+        # @return [void]
+        def remove_streaming_connection(session)
+          session.streaming_connection = nil
+          session.touch!
+          logger.debug { "Streaming connection removed: #{session.id}" }
+        end
+
+        protected
+
+        # Override: Called when a session is terminated to clean up streaming connections.
+        def on_session_terminated(session)
+          close_streaming_connection(session)
+        end
+
+        # Override: Returns metadata for new HTTP stream sessions.
+        def create_session_metadata
+          { streaming_connection: nil }
+        end
+
+        # Override: Checks if a session can receive messages (has streaming connection).
+        def can_send_message_to_session?(session)
+          session.streaming?
+        end
+
+        # Override: Sends a message to a session via the stream handler.
+        def message_sent_to_session?(session, message)
+          @transport.stream_handler.send_message_to_session(session, message)
+        end
+
+        private
+
+        # Closes a session's streaming connection if it exists.
+        #
+        # @param session [Session] The session whose connection to close
+        # @return [void]
+        def close_streaming_connection(session)
+          return unless session&.streaming_connection
+
+          begin
+            session.streaming_connection.close
+          rescue StandardError => e
+            logger.warn { "Error closing streaming connection for #{session.id}: #{e.message}" }
+          end
+
+          session.streaming_connection = nil
+        end
+      end
+    end
+  end
+end