vector_mcp 0.3.1 → 0.3.3

data/lib/vector_mcp/middleware/base.rb

@@ -0,0 +1,171 @@
+# frozen_string_literal: true
+
+module VectorMCP
+  module Middleware
+    # Base class for all middleware implementations
+    # Provides common functionality and hook method templates
+    class Base
+      # Initialize middleware with optional configuration
+      # @param config [Hash] Configuration options
+      def initialize(config = {})
+        @config = config
+        @logger = VectorMCP.logger_for("middleware.#{self.class.name.split("::").last.downcase}")
+      end
+
+      # Generic hook dispatcher - override specific hook methods instead
+      # @param hook_type [String] Type of hook being executed
+      # @param context [VectorMCP::Middleware::Context] Execution context
+      def call(hook_type, context)
+        # Generic middleware hook execution
+      end
+
+      # Tool operation hooks
+
+      # Called before tool execution
+      # @param context [VectorMCP::Middleware::Context] Execution context
+      def before_tool_call(context)
+        # Override in subclasses
+      end
+
+      # Called after successful tool execution
+      # @param context [VectorMCP::Middleware::Context] Execution context with result
+      def after_tool_call(context)
+        # Override in subclasses
+      end
+
+      # Called when tool execution fails
+      # @param context [VectorMCP::Middleware::Context] Execution context with error
+      def on_tool_error(context)
+        # Override in subclasses
+      end
+
+      # Resource operation hooks
+
+      # Called before resource read
+      # @param context [VectorMCP::Middleware::Context] Execution context
+      def before_resource_read(context)
+        # Override in subclasses
+      end
+
+      # Called after successful resource read
+      # @param context [VectorMCP::Middleware::Context] Execution context with result
+      def after_resource_read(context)
+        # Override in subclasses
+      end
+
+      # Called when resource read fails
+      # @param context [VectorMCP::Middleware::Context] Execution context with error
+      def on_resource_error(context)
+        # Override in subclasses
+      end
+
+      # Prompt operation hooks
+
+      # Called before prompt get
+      # @param context [VectorMCP::Middleware::Context] Execution context
+      def before_prompt_get(context)
+        # Override in subclasses
+      end
+
+      # Called after successful prompt get
+      # @param context [VectorMCP::Middleware::Context] Execution context with result
+      def after_prompt_get(context)
+        # Override in subclasses
+      end
+
+      # Called when prompt get fails
+      # @param context [VectorMCP::Middleware::Context] Execution context with error
+      def on_prompt_error(context)
+        # Override in subclasses
+      end
+
+      # Sampling operation hooks
+
+      # Called before sampling request
+      # @param context [VectorMCP::Middleware::Context] Execution context
+      def before_sampling_request(context)
+        # Override in subclasses
+      end
+
+      # Called after successful sampling response
+      # @param context [VectorMCP::Middleware::Context] Execution context with result
+      def after_sampling_response(context)
+        # Override in subclasses
+      end
+
+      # Called when sampling fails
+      # @param context [VectorMCP::Middleware::Context] Execution context with error
+      def on_sampling_error(context)
+        # Override in subclasses
+      end
+
+      # Transport operation hooks
+
+      # Called before any request processing
+      # @param context [VectorMCP::Middleware::Context] Execution context
+      def before_request(context)
+        # Override in subclasses
+      end
+
+      # Called after successful response
+      # @param context [VectorMCP::Middleware::Context] Execution context with result
+      def after_response(context)
+        # Override in subclasses
+      end
+
+      # Called when transport error occurs
+      # @param context [VectorMCP::Middleware::Context] Execution context with error
+      def on_transport_error(context)
+        # Override in subclasses
+      end
+
+      # Authentication hooks
+
+      # Called before authentication
+      # @param context [VectorMCP::Middleware::Context] Execution context
+      def before_auth(context)
+        # Override in subclasses
+      end
+
+      # Called after successful authentication
+      # @param context [VectorMCP::Middleware::Context] Execution context with result
+      def after_auth(context)
+        # Override in subclasses
+      end
+
+      # Called when authentication fails
+      # @param context [VectorMCP::Middleware::Context] Execution context with error
+      def on_auth_error(context)
+        # Override in subclasses
+      end
+
+      protected
+
+      attr_reader :config, :logger
+
+      # Helper method to modify request parameters (if mutable)
+      # @param context [VectorMCP::Middleware::Context] Execution context
+      # @param new_params [Hash] New parameters to set
+      def modify_params(context, new_params)
+        if context.respond_to?(:params=)
+          context.params = new_params
+        else
+          @logger.warn("Cannot modify immutable params in context")
+        end
+      end
+
+      # Helper method to modify response result
+      # @param context [VectorMCP::Middleware::Context] Execution context
+      # @param new_result [Object] New result to set
+      def modify_result(context, new_result)
+        context.result = new_result
+      end
+
+      # Helper method to skip remaining hooks in the chain
+      # @param context [VectorMCP::Middleware::Context] Execution context
+      def skip_remaining_hooks(context)
+        context.skip_remaining_hooks = true
+      end
+    end
+  end
+end

data/lib/vector_mcp/middleware/context.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module VectorMCP
+  module Middleware
+    # Context object passed to middleware hooks containing operation metadata
+    # Provides access to request data, session info, and mutable response data
+    class Context
+      attr_reader :operation_type, :operation_name, :params, :session, :server, :metadata
+      attr_accessor :result, :error, :skip_remaining_hooks
+
+      # @param options [Hash] Context initialization options
+      # @option options [Symbol] :operation_type Type of operation (:tool_call, :resource_read, etc.)
+      # @option options [String] :operation_name Name of the specific operation being performed
+      # @option options [Hash] :params Request parameters
+      # @option options [VectorMCP::Session] :session Current session
+      # @option options [VectorMCP::Server] :server Server instance
+      # @option options [Hash] :metadata Additional metadata about the operation
+      def initialize(options = {})
+        @operation_type = options[:operation_type]
+        @operation_name = options[:operation_name]
+        @params = (options[:params] || {}).dup.freeze # Immutable copy
+        @session = options[:session]
+        @server = options[:server]
+        @metadata = (options[:metadata] || {}).dup
+        @result = nil
+        @error = nil
+        @skip_remaining_hooks = false
+      end
+
+      # Check if operation completed successfully
+      # @return [Boolean] true if no error occurred
+      def success?
+        @error.nil?
+      end
+
+      # Check if operation failed
+      # @return [Boolean] true if error occurred
+      def error?
+        !@error.nil?
+      end
+
+      # Get user context from session if available
+      # @return [Hash, nil] User context or nil if not authenticated
+      def user
+        @session&.security_context&.user
+      end
+
+      # Get operation timing information
+      # @return [Hash] Timing metadata
+      def timing
+        @metadata[:timing] || {}
+      end
+
+      # Add custom metadata
+      # @param key [Symbol, String] Metadata key
+      # @param value [Object] Metadata value
+      def add_metadata(key, value)
+        @metadata[key] = value
+      end
+
+      # Get all available data as hash for logging/debugging
+      # @return [Hash] Context summary
+      def to_h
+        {
+          operation_type: @operation_type,
+          operation_name: @operation_name,
+          params: @params,
+          session_id: @session&.id,
+          metadata: @metadata,
+          success: success?,
+          error: @error&.class&.name
+        }
+      end
+    end
+  end
+end

data/lib/vector_mcp/middleware/hook.rb

@@ -0,0 +1,169 @@
+# frozen_string_literal: true
+
+module VectorMCP
+  module Middleware
+    # Represents a single middleware hook with priority and execution logic
+    class Hook
+      attr_reader :middleware_class, :hook_type, :priority, :conditions
+
+      # Default priority for middleware (lower numbers execute first)
+      DEFAULT_PRIORITY = 100
+
+      # @param middleware_class [Class] The middleware class to execute
+      # @param hook_type [String, Symbol] Type of hook (before_tool_call, etc.)
+      # @param priority [Integer] Execution priority (lower numbers execute first)
+      # @param conditions [Hash] Conditions for when this hook should run
+      def initialize(middleware_class, hook_type, priority: DEFAULT_PRIORITY, conditions: {})
+        @middleware_class = middleware_class
+        @hook_type = hook_type.to_s
+        @priority = priority
+        @conditions = conditions
+
+        validate_hook_type!
+        validate_middleware_class!
+      end
+
+      # Execute this hook with the given context
+      # @param context [VectorMCP::Middleware::Context] Execution context
+      # @return [void]
+      def execute(context)
+        return unless should_execute?(context)
+
+        # Create middleware instance and execute hook
+        middleware_instance = create_middleware_instance(context)
+        execute_hook_method(middleware_instance, context)
+      rescue StandardError => e
+        handle_hook_error(e, context)
+      end
+
+      # Check if this hook should execute for the given context
+      # @param context [VectorMCP::Middleware::Context] Execution context
+      # @return [Boolean] true if hook should execute
+      def should_execute?(context)
+        return false if context.skip_remaining_hooks
+
+        # Check operation type match
+        return false unless matches_operation_type?(context)
+
+        # Check custom conditions
+        @conditions.all? { |key, value| condition_matches?(key, value, context) }
+      end
+
+      # Compare hooks for sorting by priority
+      # @param other [Hook] Other hook to compare
+      # @return [Integer] Comparison result
+      def <=>(other)
+        @priority <=> other.priority
+      end
+
+      private
+
+      def validate_hook_type!
+        return if HOOK_TYPES.include?(@hook_type)
+
+        raise InvalidHookTypeError, @hook_type
+      end
+
+      def validate_middleware_class!
+        raise ArgumentError, "middleware_class must be a Class, got #{@middleware_class.class}" unless @middleware_class.is_a?(Class)
+
+        return if @middleware_class < VectorMCP::Middleware::Base
+
+        raise ArgumentError, "middleware_class must inherit from VectorMCP::Middleware::Base"
+      end
+
+      def matches_operation_type?(context)
+        operation_prefix = @hook_type.split("_")[1..].join("_")
+
+        return true if transport_or_auth_hook?(operation_prefix)
+
+        operation_matches?(operation_prefix, context.operation_type)
+      end
+
+      def condition_matches?(key, value, context)
+        case key
+        when :only_operations, :except_operations
+          operation_condition_matches?(key, value, context)
+        when :only_users, :except_users
+          user_condition_matches?(key, value, context)
+        else
+          true # Unknown conditions are ignored
+        end
+      end
+
+      def transport_or_auth_hook?(operation_prefix)
+        %w[request response transport_error auth auth_error].include?(operation_prefix)
+      end
+
+      def operation_matches?(operation_prefix, operation_type)
+        case operation_prefix
+        when "tool_call", "tool_error"
+          operation_type == :tool_call
+        when "resource_read", "resource_error"
+          operation_type == :resource_read
+        when "prompt_get", "prompt_error"
+          operation_type == :prompt_get
+        when "sampling_request", "sampling_response", "sampling_error"
+          operation_type == :sampling
+        else
+          true
+        end
+      end
+
+      def operation_condition_matches?(key, value, context)
+        included = Array(value).include?(context.operation_name)
+        key == :only_operations ? included : !included
+      end
+
+      def user_condition_matches?(key, value, context)
+        user_id = context.user&.[](:user_id) || context.user&.[]("user_id")
+        included = Array(value).include?(user_id)
+        key == :only_users ? included : !included
+      end
+
+      def create_middleware_instance(_context)
+        if @middleware_class.respond_to?(:new)
+          @middleware_class.new
+        else
+          @middleware_class
+        end
+      end
+
+      def execute_hook_method(middleware_instance, context)
+        method_name = @hook_type
+
+        if middleware_instance.respond_to?(method_name)
+          middleware_instance.public_send(method_name, context)
+        elsif middleware_instance.respond_to?(:call)
+          # Fallback to generic call method
+          middleware_instance.call(@hook_type, context)
+        else
+          raise MiddlewareError,
+                "Middleware #{@middleware_class} does not respond to #{method_name} or call",
+                middleware_class: @middleware_class
+        end
+      end
+
+      def handle_hook_error(error, context)
+        # Log the error but don't break the chain unless it's critical
+        logger = VectorMCP.logger_for("middleware")
+        logger.error("Middleware hook failed") do
+          {
+            middleware: @middleware_class.name,
+            hook_type: @hook_type,
+            operation: context.operation_name,
+            error: error.message
+          }
+        end
+
+        # Re-raise if it's a critical error that should stop execution
+        return unless error.is_a?(VectorMCP::Error) || @conditions[:critical] == true
+
+        raise MiddlewareError,
+              "Critical middleware failure in #{@middleware_class}",
+              original_error: error,
+              middleware_class: @middleware_class
+      end
+    end
+  end
+end

data/lib/vector_mcp/middleware/manager.rb

@@ -0,0 +1,179 @@
+# frozen_string_literal: true
+
+require "concurrent-ruby"
+
+module VectorMCP
+  module Middleware
+    # Central manager for middleware hooks and execution
+    # Thread-safe registry and execution engine for all middleware
+    class Manager
+      def initialize
+        @hooks = Concurrent::Map.new { |h, k| h[k] = Concurrent::Array.new }
+        @logger = VectorMCP.logger_for("middleware.manager")
+      end
+
+      # Register a middleware for specific hook types
+      # @param middleware_class [Class] Middleware class inheriting from Base
+      # @param hooks [Array<String, Symbol>] Hook types to register for
+      # @param priority [Integer] Execution priority (lower numbers execute first)
+      # @param conditions [Hash] Conditions for when middleware should run
+      # @example
+      #   manager.register(MyMiddleware, [:before_tool_call, :after_tool_call])
+      #   manager.register(AuthMiddleware, :before_request, priority: 10)
+      def register(middleware_class, hooks, priority: Hook::DEFAULT_PRIORITY, conditions: {})
+        Array(hooks).each do |hook_type|
+          hook = Hook.new(middleware_class, hook_type, priority: priority, conditions: conditions)
+          add_hook(hook)
+        end
+
+        @logger.debug("Registered middleware") do
+          {
+            middleware: middleware_class.name,
+            hooks: Array(hooks),
+            priority: priority
+          }
+        end
+      end
+
+      # Remove all hooks for a specific middleware class
+      # @param middleware_class [Class] Middleware class to remove
+      def unregister(middleware_class)
+        removed_count = 0
+
+        @hooks.each_value do |hook_array|
+          removed_count += hook_array.delete_if { |hook| hook.middleware_class == middleware_class }.size
+        end
+
+        @logger.debug("Unregistered middleware") do
+          {
+            middleware: middleware_class.name,
+            hooks_removed: removed_count
+          }
+        end
+      end
+
+      # Execute all hooks for a specific hook type with timing
+      # @param hook_type [String, Symbol] Type of hook to execute
+      # @param context [VectorMCP::Middleware::Context] Execution context
+      # @return [VectorMCP::Middleware::Context] Modified context
+      def execute_hooks(hook_type, context)
+        hook_type_str = hook_type.to_s
+        hooks = get_sorted_hooks(hook_type_str)
+
+        return context if hooks.empty?
+
+        execution_state = initialize_execution_state(hook_type_str, hooks, context)
+        execute_hook_chain(hooks, context, execution_state)
+        finalize_execution(context, execution_state)
+
+        context
+      end
+
+      # Get statistics about registered middleware
+      # @return [Hash] Statistics summary
+      def stats
+        hook_counts = {}
+        total_hooks = 0
+
+        @hooks.each do |hook_type, hook_array|
+          count = hook_array.size
+          hook_counts[hook_type] = count
+          total_hooks += count
+        end
+
+        {
+          total_hooks: total_hooks,
+          hook_types: hook_counts.keys.sort,
+          hooks_by_type: hook_counts
+        }
+      end
+
+      # Clear all registered hooks (useful for testing)
+      def clear!
+        @hooks.clear
+        @logger.debug("Cleared all middleware hooks")
+      end
+
+      private
+
+      def add_hook(hook)
+        hook_type = hook.hook_type
+        hook_array = @hooks[hook_type]
+
+        # Insert hook in sorted position by priority
+        insertion_index = hook_array.find_index { |existing_hook| existing_hook.priority > hook.priority }
+        if insertion_index
+          hook_array.insert(insertion_index, hook)
+        else
+          hook_array << hook
+        end
+      end
+
+      def get_sorted_hooks(hook_type)
+        @hooks[hook_type].to_a
+      end
+
+      def initialize_execution_state(hook_type_str, hooks, _context)
+        start_time = Time.now
+
+        # Executing middleware hooks
+
+        {
+          hook_type: hook_type_str,
+          start_time: start_time,
+          executed_count: 0,
+          total_hooks: hooks.size
+        }
+      end
+
+      def execute_hook_chain(hooks, context, execution_state)
+        hooks.each do |hook|
+          break if context.skip_remaining_hooks
+
+          hook.execute(context)
+          execution_state[:executed_count] += 1
+        rescue MiddlewareError => e
+          handle_critical_error(e, execution_state[:hook_type], context)
+          break
+        rescue StandardError => e
+          handle_standard_error(e, execution_state[:hook_type])
+          # Continue with other hooks for non-critical errors
+        end
+      end
+
+      def finalize_execution(context, execution_state)
+        execution_time = Time.now - execution_state[:start_time]
+
+        context.add_metadata(:middleware_timing, {
+                               hook_type: execution_state[:hook_type],
+                               execution_time: execution_time,
+                               hooks_executed: execution_state[:executed_count],
+                               hooks_total: execution_state[:total_hooks]
+                             })
+
+        # Completed middleware execution
+      end
+
+      def handle_critical_error(error, hook_type, context)
+        @logger.error("Critical middleware error") do
+          {
+            middleware: error.middleware_class&.name,
+            hook_type: hook_type,
+            error: error.message
+          }
+        end
+
+        context.error = error
+      end
+
+      def handle_standard_error(error, hook_type)
+        @logger.error("Unexpected middleware error") do
+          {
+            hook_type: hook_type,
+            error: error.message
+          }
+        end
+      end
+    end
+  end
+end

data/lib/vector_mcp/middleware.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+# Middleware framework for VectorMCP
+# Provides pluggable hooks around MCP operations
+require_relative "errors"
+require_relative "middleware/context"
+require_relative "middleware/hook"
+require_relative "middleware/manager"
+require_relative "middleware/base"
+
+module VectorMCP
+  # Middleware system for pluggable hooks around MCP operations
+  # Allows developers to add custom behavior without modifying core code
+  module Middleware
+    # Hook types available in the system
+    HOOK_TYPES = %w[
+      before_tool_call after_tool_call on_tool_error
+      before_resource_read after_resource_read on_resource_error
+      before_prompt_get after_prompt_get on_prompt_error
+      before_sampling_request after_sampling_response on_sampling_error
+      before_request after_response on_transport_error
+      before_auth after_auth on_auth_error
+    ].freeze
+
+    # Error raised when invalid hook type is specified
+    class InvalidHookTypeError < VectorMCP::Error
+      def initialize(hook_type)
+        super("Invalid hook type: #{hook_type}. Valid types: #{HOOK_TYPES.join(", ")}")
+      end
+    end
+
+    # Error raised when middleware execution fails
+    class MiddlewareError < VectorMCP::Error
+      attr_reader :original_error, :middleware_class
+
+      def initialize(message, original_error: nil, middleware_class: nil)
+        super(message)
+        @original_error = original_error
+        @middleware_class = middleware_class
+      end
+    end
+  end
+end