tsikol 0.1.0

data/docs/cookbook/error-handling.md

@@ -0,0 +1,887 @@
+# Error Handling Recipe
+
+This recipe demonstrates comprehensive error handling strategies for building robust MCP servers.
+
+## Basic Error Handling
+
+### Tool Error Handling
+
+```ruby
+class SafeTool < Tsikol::Tool
+  description "Tool with comprehensive error handling"
+  
+  parameter :input do
+    type :string
+    required
+    description "Input to process"
+  end
+  
+  def execute(input:)
+    # Input validation
+    validate_input!(input)
+    
+    # Process with error handling
+    result = process_safely(input)
+    
+    # Format result
+    format_result(result)
+    
+  rescue ValidationError => e
+    # Return user-friendly validation error
+    handle_validation_error(e)
+    
+  rescue ExternalServiceError => e
+    # Handle external service failures
+    handle_external_error(e)
+    
+  rescue => e
+    # Handle unexpected errors
+    handle_unexpected_error(e)
+  end
+  
+  private
+  
+  def validate_input!(input)
+    raise ValidationError, "Input cannot be empty" if input.strip.empty?
+    raise ValidationError, "Input too long (max 1000 chars)" if input.length > 1000
+    raise ValidationError, "Invalid characters" unless input.match?(/\A[\w\s\-.,!?]+\z/)
+  end
+  
+  def process_safely(input)
+    with_timeout(5) do
+      with_retry(3) do
+        perform_processing(input)
+      end
+    end
+  end
+  
+  def with_timeout(seconds)
+    Timeout.timeout(seconds) do
+      yield
+    end
+  rescue Timeout::Error
+    raise ExternalServiceError, "Operation timed out after #{seconds} seconds"
+  end
+  
+  def with_retry(max_attempts)
+    attempts = 0
+    begin
+      attempts += 1
+      yield
+    rescue ExternalServiceError => e
+      if attempts < max_attempts
+        log :warning, "Retrying after error", attempt: attempts, error: e.message
+        sleep(attempts * 0.5)  # Exponential backoff
+        retry
+      else
+        raise
+      end
+    end
+  end
+  
+  def handle_validation_error(error)
+    log :info, "Validation failed", error: error.message
+    "Validation Error: #{error.message}"
+  end
+  
+  def handle_external_error(error)
+    log :error, "External service error", error: error.message
+    "Service temporarily unavailable. Please try again later."
+  end
+  
+  def handle_unexpected_error(error)
+    error_id = SecureRandom.uuid
+    log :error, "Unexpected error", error_id: error_id, error: error.class.name, message: error.message
+    "An unexpected error occurred (ID: #{error_id}). Please contact support."
+  end
+end
+
+# Custom error classes
+class ValidationError < StandardError; end
+class ExternalServiceError < StandardError; end
+```
+
+### Resource Error Handling
+
+```ruby
+class ResilientResource < Tsikol::Resource
+  uri "data/resilient"
+  description "Resource with fallback mechanisms"
+  
+  def read
+    # Try primary data source
+    fetch_from_primary
+  rescue PrimarySourceError => e
+    log :warning, "Primary source failed, trying secondary", error: e.message
+    
+    # Fallback to secondary source
+    fetch_from_secondary
+  rescue SecondarySourceError => e
+    log :error, "Secondary source also failed", error: e.message
+    
+    # Return cached or default data
+    fallback_response
+  rescue => e
+    log :error, "Unexpected error in resource", error: e.class.name
+    error_response("Resource temporarily unavailable")
+  end
+  
+  private
+  
+  def fetch_from_primary
+    # Simulate primary data source
+    raise PrimarySourceError, "Database connection failed" if rand > 0.9
+    
+    {
+      source: "primary",
+      data: fetch_current_data,
+      timestamp: Time.now.iso8601
+    }.to_json
+  end
+  
+  def fetch_from_secondary
+    # Simulate secondary data source
+    raise SecondarySourceError, "API timeout" if rand > 0.8
+    
+    {
+      source: "secondary",
+      data: fetch_cached_data,
+      timestamp: Time.now.iso8601,
+      warning: "Using secondary data source"
+    }.to_json
+  end
+  
+  def fallback_response
+    {
+      source: "fallback",
+      data: default_data,
+      timestamp: Time.now.iso8601,
+      error: "All data sources unavailable, returning default data"
+    }.to_json
+  end
+  
+  def error_response(message)
+    {
+      error: message,
+      timestamp: Time.now.iso8601,
+      retry_after: 60
+    }.to_json
+  end
+end
+
+class PrimarySourceError < StandardError; end
+class SecondarySourceError < StandardError; end
+```
+
+## Error Handling Middleware
+
+### Comprehensive Error Middleware
+
+```ruby
+class ErrorHandlingMiddleware < Tsikol::Middleware
+  def initialize(app, options = {})
+    @app = app
+    @log_errors = options.fetch(:log_errors, true)
+    @include_backtrace = options.fetch(:include_backtrace, false)
+    @error_callbacks = options[:error_callbacks] || {}
+    @error_reporters = options[:error_reporters] || []
+  end
+  
+  def call(request)
+    # Add error context
+    Thread.current[:error_context] = {
+      request_id: request["id"],
+      method: request["method"],
+      timestamp: Time.now
+    }
+    
+    # Process request
+    @app.call(request)
+    
+  rescue StandardError => e
+    handle_error(request, e)
+  ensure
+    Thread.current[:error_context] = nil
+  end
+  
+  private
+  
+  def handle_error(request, error)
+    error_info = analyze_error(error)
+    
+    # Log error
+    log_error(error_info) if @log_errors
+    
+    # Report to external services
+    report_error(error_info)
+    
+    # Execute callbacks
+    execute_error_callbacks(error_info)
+    
+    # Return appropriate error response
+    error_response(request["id"], error_info)
+  end
+  
+  def analyze_error(error)
+    {
+      error_class: error.class.name,
+      message: error.message,
+      backtrace: @include_backtrace ? error.backtrace : nil,
+      category: categorize_error(error),
+      severity: determine_severity(error),
+      context: Thread.current[:error_context],
+      timestamp: Time.now
+    }
+  end
+  
+  def categorize_error(error)
+    case error
+    when Tsikol::ValidationError, ArgumentError
+      :validation
+    when Tsikol::NotFoundError
+      :not_found
+    when Timeout::Error, Net::ReadTimeout
+      :timeout
+    when Redis::BaseError, PG::Error
+      :database
+    when Net::HTTPError, Faraday::Error
+      :network
+    else
+      :internal
+    end
+  end
+  
+  def determine_severity(error)
+    case categorize_error(error)
+    when :validation, :not_found
+      :info
+    when :timeout, :network
+      :warning
+    when :database
+      :error
+    else
+      :critical
+    end
+  end
+  
+  def error_response(id, error_info)
+    code, message = case error_info[:category]
+    when :validation
+      [-32602, "Invalid params"]
+    when :not_found
+      [-32601, "Method not found"]
+    when :timeout
+      [-32001, "Request timeout"]
+    when :database, :network
+      [-32002, "Service unavailable"]
+    else
+      [-32603, "Internal error"]
+    end
+    
+    response = {
+      jsonrpc: "2.0",
+      id: id,
+      error: {
+        code: code,
+        message: message,
+        data: build_error_data(error_info)
+      }
+    }
+    
+    response
+  end
+  
+  def build_error_data(error_info)
+    data = {
+      category: error_info[:category],
+      details: sanitize_message(error_info[:message])
+    }
+    
+    if @include_backtrace && error_info[:backtrace]
+      data[:backtrace] = error_info[:backtrace].first(5)
+    end
+    
+    data
+  end
+  
+  def sanitize_message(message)
+    # Remove sensitive information
+    message.gsub(/password=\S+/i, 'password=[REDACTED]')
+           .gsub(/key=\S+/i, 'key=[REDACTED]')
+           .gsub(/token=\S+/i, 'token=[REDACTED]')
+  end
+  
+  def execute_error_callbacks(error_info)
+    callback = @error_callbacks[error_info[:category]]
+    callback&.call(error_info)
+  rescue => e
+    log :error, "Error callback failed", error: e.message
+  end
+  
+  def report_error(error_info)
+    @error_reporters.each do |reporter|
+      reporter.report(error_info)
+    rescue => e
+      log :error, "Error reporter failed", reporter: reporter.class.name, error: e.message
+    end
+  end
+end
+```
+
+### Circuit Breaker Pattern
+
+```ruby
+class CircuitBreaker
+  def initialize(options = {})
+    @threshold = options[:threshold] || 5
+    @timeout = options[:timeout] || 60
+    @half_open_requests = options[:half_open_requests] || 1
+    
+    @failure_count = 0
+    @last_failure_time = nil
+    @state = :closed
+    @half_open_attempts = 0
+    @mutex = Mutex.new
+  end
+  
+  def call
+    @mutex.synchronize do
+      case @state
+      when :open
+        if can_attempt_reset?
+          @state = :half_open
+          @half_open_attempts = 0
+        else
+          raise CircuitOpenError, "Circuit breaker is open"
+        end
+      when :half_open
+        if @half_open_attempts >= @half_open_requests
+          raise CircuitOpenError, "Circuit breaker is half-open, limit reached"
+        end
+        @half_open_attempts += 1
+      end
+    end
+    
+    # Try the operation
+    result = yield
+    
+    # Success - update state
+    @mutex.synchronize do
+      @failure_count = 0
+      @state = :closed if @state == :half_open
+    end
+    
+    result
+    
+  rescue => e
+    @mutex.synchronize do
+      @failure_count += 1
+      @last_failure_time = Time.now
+      
+      if @failure_count >= @threshold
+        @state = :open
+        log :warning, "Circuit breaker opened", failures: @failure_count
+      end
+    end
+    
+    raise
+  end
+  
+  def state
+    @mutex.synchronize { @state }
+  end
+  
+  def reset
+    @mutex.synchronize do
+      @failure_count = 0
+      @state = :closed
+      @last_failure_time = nil
+    end
+  end
+  
+  private
+  
+  def can_attempt_reset?
+    return false unless @last_failure_time
+    Time.now - @last_failure_time >= @timeout
+  end
+end
+
+class CircuitOpenError < StandardError; end
+
+# Usage in tools
+class ProtectedTool < Tsikol::Tool
+  def initialize
+    super
+    @circuit_breaker = CircuitBreaker.new(threshold: 3, timeout: 30)
+  end
+  
+  def execute(query:)
+    @circuit_breaker.call do
+      # Potentially failing operation
+      external_api_call(query)
+    end
+  rescue CircuitOpenError => e
+    log :warning, "Circuit breaker prevented call"
+    "Service temporarily unavailable. Please try again later."
+  end
+end
+```
+
+## Graceful Degradation
+
+### Feature Flags and Fallbacks
+
+```ruby
+class DegradableService
+  def initialize(options = {})
+    @features = options[:features] || {}
+    @fallbacks = options[:fallbacks] || {}
+  end
+  
+  def execute(operation, params)
+    if feature_enabled?(operation)
+      execute_with_fallback(operation, params)
+    else
+      "Feature '#{operation}' is currently disabled"
+    end
+  end
+  
+  private
+  
+  def feature_enabled?(operation)
+    @features.fetch(operation, true)
+  end
+  
+  def execute_with_fallback(operation, params)
+    primary_handler(operation, params)
+  rescue => e
+    log :warning, "Primary handler failed, using fallback", 
+        operation: operation, error: e.message
+    
+    fallback = @fallbacks[operation]
+    if fallback
+      fallback.call(params)
+    else
+      raise
+    end
+  end
+  
+  def primary_handler(operation, params)
+    case operation
+    when :search
+      perform_full_search(params)
+    when :analyze
+      perform_deep_analysis(params)
+    else
+      raise NotImplementedError, "Unknown operation: #{operation}"
+    end
+  end
+end
+
+# Configuration
+service = DegradableService.new(
+  features: {
+    search: true,
+    analyze: false  # Disabled due to high load
+  },
+  fallbacks: {
+    search: ->(params) { perform_basic_search(params) },
+    analyze: ->(params) { "Analysis temporarily unavailable" }
+  }
+)
+```
+
+### Progressive Enhancement
+
+```ruby
+class ProgressiveResource < Tsikol::Resource
+  uri "data/progressive"
+  description "Resource with progressive data quality"
+  
+  def read
+    start_time = Time.now
+    timeout = 5.0  # 5 second budget
+    
+    data = {
+      basic: fetch_basic_data,
+      timestamp: Time.now.iso8601
+    }
+    
+    # Progressively add more data if time permits
+    if time_remaining(start_time, timeout) > 2
+      begin
+        data[:enhanced] = fetch_enhanced_data
+      rescue => e
+        log :warning, "Failed to fetch enhanced data", error: e.message
+        data[:enhanced] = { error: "Unavailable" }
+      end
+    end
+    
+    if time_remaining(start_time, timeout) > 1
+      begin
+        data[:premium] = fetch_premium_data
+      rescue => e
+        log :warning, "Failed to fetch premium data", error: e.message
+      end
+    end
+    
+    data.to_json
+  end
+  
+  private
+  
+  def time_remaining(start_time, timeout)
+    timeout - (Time.now - start_time)
+  end
+  
+  def fetch_basic_data
+    # Always available, cached data
+    { status: "operational", users: 1000 }
+  end
+  
+  def fetch_enhanced_data
+    # Might fail or be slow
+    sleep(1)  # Simulate work
+    { metrics: calculate_metrics, trends: analyze_trends }
+  end
+  
+  def fetch_premium_data
+    # Expensive operation
+    sleep(2)  # Simulate work
+    { predictions: generate_predictions }
+  end
+end
+```
+
+## Error Recovery Strategies
+
+### Retry with Backoff
+
+```ruby
+class RetryableOperation
+  def self.execute(options = {})
+    max_attempts = options[:max_attempts] || 3
+    base_delay = options[:base_delay] || 1
+    max_delay = options[:max_delay] || 30
+    multiplier = options[:multiplier] || 2
+    jitter = options[:jitter] || true
+    
+    attempt = 0
+    last_error = nil
+    
+    loop do
+      attempt += 1
+      
+      begin
+        return yield(attempt)
+      rescue => e
+        last_error = e
+        
+        if attempt >= max_attempts || !retryable_error?(e)
+          raise last_error
+        end
+        
+        delay = calculate_delay(attempt, base_delay, max_delay, multiplier, jitter)
+        log :info, "Retrying after error", 
+            attempt: attempt, 
+            delay: delay, 
+            error: e.message
+        
+        sleep(delay)
+      end
+    end
+  end
+  
+  private
+  
+  def self.retryable_error?(error)
+    case error
+    when Net::ReadTimeout, Net::OpenTimeout, Timeout::Error
+      true
+    when Redis::BaseError
+      true
+    when StandardError
+      # Check for specific error messages
+      error.message.match?(/temporary|timeout|unavailable/i)
+    else
+      false
+    end
+  end
+  
+  def self.calculate_delay(attempt, base, max, multiplier, jitter)
+    delay = [base * (multiplier ** (attempt - 1)), max].min
+    
+    if jitter
+      # Add random jitter (±25%)
+      delay = delay * (0.75 + rand * 0.5)
+    end
+    
+    delay
+  end
+end
+
+# Usage
+class RobustTool < Tsikol::Tool
+  def execute(params)
+    RetryableOperation.execute(max_attempts: 5, base_delay: 0.5) do |attempt|
+      log :debug, "Attempting operation", attempt: attempt
+      perform_operation(params)
+    end
+  end
+end
+```
+
+### Bulkhead Pattern
+
+```ruby
+class BulkheadExecutor
+  def initialize(options = {})
+    @pools = {}
+    @default_pool_size = options[:default_pool_size] || 10
+    @reject_policy = options[:reject_policy] || :abort
+  end
+  
+  def execute(pool_name, &block)
+    pool = get_or_create_pool(pool_name)
+    
+    case @reject_policy
+    when :abort
+      pool.post(&block)
+    when :caller_runs
+      if pool.queue_length >= pool.max_queue
+        # Run in caller thread if pool is full
+        yield
+      else
+        pool.post(&block)
+      end
+    when :discard
+      # Silently discard if pool is full
+      pool.post(&block) rescue nil
+    end
+  rescue Concurrent::RejectedExecutionError
+    raise BulkheadFullError, "Pool '#{pool_name}' is at capacity"
+  end
+  
+  def shutdown
+    @pools.each do |name, pool|
+      pool.shutdown
+      pool.wait_for_termination(5)
+    end
+  end
+  
+  private
+  
+  def get_or_create_pool(name)
+    @pools[name] ||= Concurrent::ThreadPoolExecutor.new(
+      min_threads: 2,
+      max_threads: @default_pool_size,
+      max_queue: @default_pool_size * 2,
+      fallback_policy: @reject_policy
+    )
+  end
+end
+
+class BulkheadFullError < StandardError; end
+
+# Usage - isolate different operations
+bulkhead = BulkheadExecutor.new(default_pool_size: 5)
+
+# Critical operations get their own pool
+bulkhead.execute(:critical) do
+  process_payment(order)
+end
+
+# Less critical operations share a pool
+bulkhead.execute(:background) do
+  send_notification(user)
+end
+```
+
+## Error Reporting
+
+### Structured Error Reporter
+
+```ruby
+class ErrorReporter
+  def initialize(options = {})
+    @service_name = options[:service_name] || "mcp-server"
+    @environment = options[:environment] || "production"
+    @reporters = []
+  end
+  
+  def add_reporter(reporter)
+    @reporters << reporter
+  end
+  
+  def report(error, context = {})
+    error_data = build_error_data(error, context)
+    
+    @reporters.each do |reporter|
+      Thread.new do
+        begin
+          reporter.report(error_data)
+        rescue => e
+          # Don't let reporter errors affect main flow
+          log :error, "Reporter failed", 
+              reporter: reporter.class.name, 
+              error: e.message
+        end
+      end
+    end
+  end
+  
+  private
+  
+  def build_error_data(error, context)
+    {
+      service: @service_name,
+      environment: @environment,
+      error: {
+        class: error.class.name,
+        message: error.message,
+        backtrace: error.backtrace&.first(20)
+      },
+      context: context.merge(
+        timestamp: Time.now.iso8601,
+        thread_id: Thread.current.object_id,
+        process_id: Process.pid
+      ),
+      system: {
+        ruby_version: RUBY_VERSION,
+        platform: RUBY_PLATFORM,
+        memory_usage: memory_usage
+      }
+    }
+  end
+  
+  def memory_usage
+    `ps -o rss= -p #{Process.pid}`.to_i / 1024 rescue nil
+  end
+end
+
+# Example reporters
+class LogReporter
+  def report(error_data)
+    log :error, "Error reported", data: error_data
+  end
+end
+
+class SentryReporter
+  def report(error_data)
+    Sentry.capture_exception(
+      StandardError.new(error_data[:error][:message]),
+      extra: error_data
+    )
+  end
+end
+
+# Setup
+error_reporter = ErrorReporter.new(
+  service_name: "my-mcp-server",
+  environment: ENV['RACK_ENV']
+)
+error_reporter.add_reporter(LogReporter.new)
+error_reporter.add_reporter(SentryReporter.new) if ENV['SENTRY_DSN']
+```
+
+## Testing Error Handling
+
+```ruby
+require 'minitest/autorun'
+
+class ErrorHandlingTest < Minitest::Test
+  def setup
+    @server = Tsikol::Server.new(name: "test")
+    @server.use ErrorHandlingMiddleware, include_backtrace: true
+    @server.register_tool_instance(FaultyTool.new)
+    @client = Tsikol::TestHelpers::TestClient.new(@server)
+  end
+  
+  def test_handles_validation_errors
+    response = @client.call_tool("faulty_tool", {
+      "action" => "validate",
+      "input" => ""
+    })
+    
+    assert_error_response(response, -32602)
+    assert_match /Invalid params/, response[:error][:message]
+    assert_equal :validation, response[:error][:data][:category]
+  end
+  
+  def test_retries_transient_failures
+    response = @client.call_tool("faulty_tool", {
+      "action" => "transient",
+      "fail_times" => 2
+    })
+    
+    # Should succeed after retries
+    assert_successful_response(response)
+  end
+  
+  def test_circuit_breaker_opens
+    # Make requests fail repeatedly
+    3.times do
+      @client.call_tool("faulty_tool", {
+        "action" => "external",
+        "should_fail" => true
+      })
+    end
+    
+    # Circuit should be open
+    response = @client.call_tool("faulty_tool", {
+      "action" => "external",
+      "should_fail" => false
+    })
+    
+    assert_error_response(response)
+    assert_match /circuit.*open/i, response[:error][:message]
+  end
+end
+
+class FaultyTool < Tsikol::Tool
+  def initialize
+    super
+    @attempt_count = 0
+    @circuit_breaker = CircuitBreaker.new(threshold: 3)
+  end
+  
+  def execute(action:, **params)
+    case action
+    when "validate"
+      raise ValidationError, "Input cannot be empty" if params[:input].empty?
+    when "transient"
+      @attempt_count += 1
+      if @attempt_count <= params[:fail_times]
+        raise ExternalServiceError, "Transient failure"
+      end
+      "Success after #{@attempt_count} attempts"
+    when "external"
+      @circuit_breaker.call do
+        if params[:should_fail]
+          raise ExternalServiceError, "External service failed"
+        end
+        "External call succeeded"
+      end
+    end
+  end
+end
+```
+
+## Best Practices
+
+1. **Fail fast** for unrecoverable errors
+2. **Retry with backoff** for transient failures
+3. **Use circuit breakers** for external dependencies
+4. **Provide fallbacks** for degraded functionality
+5. **Log appropriately** - don't flood logs with expected errors
+6. **Sanitize error messages** - remove sensitive data
+7. **Monitor error rates** and set up alerts
+8. **Test error paths** as thoroughly as happy paths
+
+## Next Steps
+
+- Implement [Logging](logging.md) for error tracking
+- Add [Monitoring](monitoring.md) for error metrics
+- Review [Testing](../guides/testing.md) error scenarios
+- Set up [Authentication](authentication.md) error handling