tsikol 0.1.0

data/docs/guides/middleware.md

@@ -0,0 +1,823 @@
+# Middleware Guide
+
+Middleware in Tsikol provides a powerful way to add cross-cutting concerns to your MCP server. From logging and authentication to rate limiting and error handling, middleware helps keep your tools and resources focused on their core functionality.
+
+## Table of Contents
+
+1. [What is Middleware?](#what-is-middleware)
+2. [Built-in Middleware](#built-in-middleware)
+3. [Creating Custom Middleware](#creating-custom-middleware)
+4. [Middleware Chain](#middleware-chain)
+5. [Request/Response Manipulation](#requestresponse-manipulation)
+6. [Advanced Patterns](#advanced-patterns)
+7. [Testing Middleware](#testing-middleware)
+
+## What is Middleware?
+
+Middleware components:
+- Intercept requests before they reach tools/resources
+- Process responses before returning to the client
+- Handle cross-cutting concerns (logging, auth, etc.)
+- Can short-circuit the request chain
+- Execute in a defined order
+
+## Built-in Middleware
+
+### Logging Middleware
+
+Log all requests and responses:
+
+```ruby
+Tsikol.server "my-server" do
+  use Tsikol::LoggingMiddleware
+  
+  # Or with options
+  use Tsikol::LoggingMiddleware, 
+      level: :debug,
+      include_params: true,
+      include_response: true
+end
+```
+
+### Rate Limiting Middleware
+
+Prevent abuse with rate limiting:
+
+```ruby
+Tsikol.server "my-server" do
+  use Tsikol::RateLimitMiddleware,
+      max_requests: 100,      # Per window
+      window_seconds: 60,     # Time window
+      by: :client_id         # Group by client
+end
+```
+
+### Error Handling Middleware
+
+Consistent error handling:
+
+```ruby
+Tsikol.server "my-server" do
+  use Tsikol::ErrorHandlingMiddleware,
+      log_errors: true,
+      include_backtrace: false,
+      error_handler: ->(error) { notify_error_service(error) }
+end
+```
+
+### Metrics Middleware
+
+Collect performance metrics:
+
+```ruby
+Tsikol.server "my-server" do
+  use Tsikol::MetricsMiddleware,
+      include_histogram: true,
+      track_errors: true,
+      custom_tags: { environment: "production" }
+end
+```
+
+## Creating Custom Middleware
+
+### Basic Middleware Structure
+
+```ruby
+class MyMiddleware < Tsikol::Middleware
+  def initialize(app, options = {})
+    @app = app
+    @options = options
+  end
+  
+  def call(request)
+    # Before request processing
+    log(:debug, "Processing request", method: request["method"])
+    
+    # Call the next middleware or handler
+    response = @app.call(request)
+    
+    # After response processing
+    log(:debug, "Request completed", status: response[:result] ? "success" : "error")
+    
+    response
+  end
+end
+```
+
+### Authentication Middleware
+
+```ruby
+class AuthenticationMiddleware < Tsikol::Middleware
+  def initialize(app, options = {})
+    super
+    @secret_key = options[:secret_key] || ENV['MCP_SECRET_KEY']
+    @required_methods = options[:required_methods] || []
+  end
+  
+  def call(request)
+    method = request["method"]
+    
+    # Skip auth for certain methods
+    unless requires_auth?(method)
+      return @app.call(request)
+    end
+    
+    # Extract and verify token
+    token = extract_token(request)
+    
+    unless valid_token?(token)
+      return error_response(request["id"], -32001, "Unauthorized")
+    end
+    
+    # Add user context
+    request["authenticated_user"] = decode_token(token)
+    
+    @app.call(request)
+  end
+  
+  private
+  
+  def requires_auth?(method)
+    return true if @required_methods.empty?
+    @required_methods.include?(method)
+  end
+  
+  def extract_token(request)
+    # Look for token in various places
+    request.dig("params", "_token") ||
+      request.dig("params", "authorization") ||
+      request.dig("meta", "authorization")
+  end
+  
+  def valid_token?(token)
+    return false unless token
+    
+    begin
+      payload = JWT.decode(token, @secret_key, true, algorithm: 'HS256')
+      !expired?(payload[0])
+    rescue JWT::DecodeError
+      false
+    end
+  end
+  
+  def expired?(payload)
+    return false unless payload["exp"]
+    Time.now.to_i > payload["exp"]
+  end
+  
+  def decode_token(token)
+    JWT.decode(token, @secret_key, true, algorithm: 'HS256')[0]
+  rescue
+    nil
+  end
+  
+  def error_response(id, code, message)
+    {
+      jsonrpc: "2.0",
+      id: id,
+      error: {
+        code: code,
+        message: message
+      }
+    }
+  end
+end
+```
+
+### Request Validation Middleware
+
+```ruby
+class ValidationMiddleware < Tsikol::Middleware
+  def initialize(app, options = {})
+    super
+    @max_request_size = options[:max_request_size] || 1_048_576  # 1MB
+    @allowed_methods = options[:allowed_methods] || nil
+  end
+  
+  def call(request)
+    # Validate request structure
+    unless valid_jsonrpc?(request)
+      return error_response(request["id"], -32600, "Invalid Request")
+    end
+    
+    # Check request size
+    if request.to_json.bytesize > @max_request_size
+      return error_response(request["id"], -32600, "Request too large")
+    end
+    
+    # Check allowed methods
+    if @allowed_methods && !@allowed_methods.include?(request["method"])
+      return error_response(request["id"], -32601, "Method not found")
+    end
+    
+    @app.call(request)
+  end
+  
+  private
+  
+  def valid_jsonrpc?(request)
+    request.is_a?(Hash) &&
+      request["jsonrpc"] == "2.0" &&
+      request["id"] &&
+      request["method"].is_a?(String)
+  end
+end
+```
+
+### Caching Middleware
+
+```ruby
+class CachingMiddleware < Tsikol::Middleware
+  def initialize(app, options = {})
+    super
+    @cache = {}
+    @ttl = options[:ttl] || 300  # 5 minutes
+    @cacheable_methods = options[:cacheable_methods] || ["resources/read"]
+  end
+  
+  def call(request)
+    method = request["method"]
+    
+    # Only cache certain methods
+    unless cacheable?(method)
+      return @app.call(request)
+    end
+    
+    # Generate cache key
+    cache_key = generate_cache_key(request)
+    
+    # Check cache
+    if cached = get_cached(cache_key)
+      log(:debug, "Cache hit", key: cache_key)
+      return cached
+    end
+    
+    # Process request
+    response = @app.call(request)
+    
+    # Cache successful responses
+    if response[:result]
+      set_cached(cache_key, response)
+    end
+    
+    response
+  end
+  
+  private
+  
+  def cacheable?(method)
+    @cacheable_methods.include?(method)
+  end
+  
+  def generate_cache_key(request)
+    params = request["params"] || {}
+    "#{request['method']}:#{params.sort.to_h.hash}"
+  end
+  
+  def get_cached(key)
+    entry = @cache[key]
+    return nil unless entry
+    
+    if Time.now - entry[:timestamp] > @ttl
+      @cache.delete(key)
+      return nil
+    end
+    
+    entry[:response]
+  end
+  
+  def set_cached(key, response)
+    @cache[key] = {
+      response: response,
+      timestamp: Time.now
+    }
+    
+    # Limit cache size
+    cleanup_cache if @cache.size > 1000
+  end
+  
+  def cleanup_cache
+    # Remove oldest entries
+    sorted = @cache.sort_by { |_, v| v[:timestamp] }
+    sorted.first(@cache.size - 800).each { |k, _| @cache.delete(k) }
+  end
+end
+```
+
+## Middleware Chain
+
+### Ordering Middleware
+
+Middleware executes in the order it's defined:
+
+```ruby
+Tsikol.server "my-server" do
+  # Executes first -> last for requests
+  # Executes last -> first for responses
+  
+  use Tsikol::LoggingMiddleware        # 1. Logs request
+  use AuthenticationMiddleware         # 2. Checks auth
+  use ValidationMiddleware             # 3. Validates
+  use Tsikol::RateLimitMiddleware     # 4. Rate limits
+  use CachingMiddleware                # 5. Checks cache
+  use Tsikol::ErrorHandlingMiddleware  # 6. Handles errors
+  
+  # Your tools and resources handle the request here
+  
+  # Response travels back through middleware in reverse
+end
+```
+
+### Conditional Middleware
+
+Apply middleware conditionally:
+
+```ruby
+class ConditionalMiddleware < Tsikol::Middleware
+  def initialize(app, options = {})
+    super
+    @condition = options[:condition] || ->(_) { true }
+    @wrapped_middleware = options[:middleware].new(app, options[:middleware_options] || {})
+  end
+  
+  def call(request)
+    if @condition.call(request)
+      @wrapped_middleware.call(request)
+    else
+      @app.call(request)
+    end
+  end
+end
+
+# Usage
+Tsikol.server "my-server" do
+  use ConditionalMiddleware,
+      condition: ->(req) { req["method"].start_with?("tools/") },
+      middleware: AuthenticationMiddleware,
+      middleware_options: { secret_key: "secret" }
+end
+```
+
+## Request/Response Manipulation
+
+### Modifying Requests
+
+```ruby
+class RequestEnrichmentMiddleware < Tsikol::Middleware
+  def call(request)
+    # Add metadata to request
+    request["meta"] ||= {}
+    request["meta"]["timestamp"] = Time.now.iso8601
+    request["meta"]["request_id"] = SecureRandom.uuid
+    
+    # Add default parameters
+    if request["method"] == "tools/call"
+      request["params"] ||= {}
+      request["params"]["_metadata"] = {
+        server_version: Tsikol::VERSION,
+        ruby_version: RUBY_VERSION
+      }
+    end
+    
+    @app.call(request)
+  end
+end
+```
+
+### Modifying Responses
+
+```ruby
+class ResponseFormattingMiddleware < Tsikol::Middleware
+  def call(request)
+    response = @app.call(request)
+    
+    # Add metadata to all responses
+    if response[:result]
+      response[:result] = {
+        data: response[:result],
+        meta: {
+          timestamp: Time.now.iso8601,
+          duration_ms: calculate_duration(request),
+          server: @server.name
+        }
+      }
+    end
+    
+    # Format error responses
+    if response[:error]
+      response[:error][:data] ||= {}
+      response[:error][:data][:request_id] = request.dig("meta", "request_id")
+    end
+    
+    response
+  end
+  
+  private
+  
+  def calculate_duration(request)
+    start_time = request.dig("meta", "_start_time")
+    return nil unless start_time
+    ((Time.now - start_time) * 1000).round(2)
+  end
+end
+```
+
+### Short-Circuit Responses
+
+```ruby
+class CircuitBreakerMiddleware < Tsikol::Middleware
+  def initialize(app, options = {})
+    super
+    @failure_threshold = options[:failure_threshold] || 5
+    @timeout = options[:timeout] || 60
+    @failure_counts = Hash.new(0)
+    @circuit_opened_at = {}
+  end
+  
+  def call(request)
+    key = circuit_key(request)
+    
+    # Check if circuit is open
+    if circuit_open?(key)
+      if should_attempt_reset?(key)
+        # Try one request
+        @circuit_opened_at.delete(key)
+      else
+        # Short-circuit
+        return error_response(
+          request["id"],
+          -32003,
+          "Service temporarily unavailable"
+        )
+      end
+    end
+    
+    # Process request
+    response = @app.call(request)
+    
+    # Track failures
+    if response[:error]
+      @failure_counts[key] += 1
+      
+      if @failure_counts[key] >= @failure_threshold
+        open_circuit(key)
+      end
+    else
+      # Reset on success
+      @failure_counts[key] = 0
+    end
+    
+    response
+  end
+  
+  private
+  
+  def circuit_key(request)
+    request["method"]
+  end
+  
+  def circuit_open?(key)
+    @circuit_opened_at.key?(key)
+  end
+  
+  def should_attempt_reset?(key)
+    Time.now - @circuit_opened_at[key] > @timeout
+  end
+  
+  def open_circuit(key)
+    @circuit_opened_at[key] = Time.now
+    log(:warning, "Circuit breaker opened", method: key)
+  end
+end
+```
+
+## Advanced Patterns
+
+### Async Middleware
+
+Handle async operations:
+
+```ruby
+class AsyncMiddleware < Tsikol::Middleware
+  def initialize(app, options = {})
+    super
+    @thread_pool = options[:thread_pool] || default_thread_pool
+  end
+  
+  def call(request)
+    if async_method?(request["method"])
+      handle_async(request)
+    else
+      @app.call(request)
+    end
+  end
+  
+  private
+  
+  def async_method?(method)
+    method.end_with?("_async")
+  end
+  
+  def handle_async(request)
+    job_id = SecureRandom.uuid
+    
+    # Start async processing
+    @thread_pool.post do
+      begin
+        result = @app.call(request)
+        store_result(job_id, result)
+      rescue => e
+        store_error(job_id, e)
+      end
+    end
+    
+    # Return immediately with job ID
+    {
+      jsonrpc: "2.0",
+      id: request["id"],
+      result: {
+        job_id: job_id,
+        status: "processing",
+        check_url: "/jobs/#{job_id}"
+      }
+    }
+  end
+  
+  def default_thread_pool
+    Concurrent::ThreadPoolExecutor.new(
+      min_threads: 2,
+      max_threads: 10,
+      max_queue: 100
+    )
+  end
+end
+```
+
+### Middleware Composition
+
+Combine multiple middleware behaviors:
+
+```ruby
+class CompositeMiddleware < Tsikol::Middleware
+  def initialize(app, *middlewares)
+    @app = app
+    @middleware_chain = build_chain(middlewares)
+  end
+  
+  def call(request)
+    @middleware_chain.call(request)
+  end
+  
+  private
+  
+  def build_chain(middlewares)
+    middlewares.reverse.reduce(@app) do |app, (middleware_class, options)|
+      middleware_class.new(app, options || {})
+    end
+  end
+end
+
+# Usage
+Tsikol.server "my-server" do
+  use CompositeMiddleware,
+      [Tsikol::LoggingMiddleware, { level: :debug }],
+      [AuthenticationMiddleware, { secret_key: "secret" }],
+      [Tsikol::RateLimitMiddleware, { max_requests: 100 }]
+end
+```
+
+### Context Propagation
+
+Pass context through the middleware chain:
+
+```ruby
+class ContextMiddleware < Tsikol::Middleware
+  def call(request)
+    # Initialize context
+    context = Thread.current[:mcp_context] = {
+      request_id: SecureRandom.uuid,
+      start_time: Time.now,
+      user: nil,
+      metadata: {}
+    }
+    
+    begin
+      response = @app.call(request)
+      
+      # Add context to response
+      if response[:result] && context[:metadata].any?
+        response[:result][:_context] = context[:metadata]
+      end
+      
+      response
+    ensure
+      # Clean up context
+      Thread.current[:mcp_context] = nil
+    end
+  end
+end
+
+# Other middleware can access context
+class LoggingMiddleware < Tsikol::Middleware
+  def call(request)
+    context = Thread.current[:mcp_context]
+    
+    log(:info, "Request received",
+        request_id: context[:request_id],
+        method: request["method"])
+    
+    @app.call(request)
+  end
+end
+```
+
+## Testing Middleware
+
+### Basic Middleware Test
+
+```ruby
+require 'minitest/autorun'
+
+class MiddlewareTest < Minitest::Test
+  def setup
+    @app = ->(_request) { { jsonrpc: "2.0", id: 1, result: "success" } }
+    @middleware = MyMiddleware.new(@app)
+  end
+  
+  def test_passes_request_through
+    request = { "jsonrpc" => "2.0", "id" => 1, "method" => "test" }
+    response = @middleware.call(request)
+    
+    assert_equal "success", response[:result]
+  end
+  
+  def test_modifies_request
+    # Test that middleware modifies request as expected
+  end
+  
+  def test_modifies_response
+    # Test that middleware modifies response as expected
+  end
+end
+```
+
+### Testing Authentication
+
+```ruby
+class AuthMiddlewareTest < Minitest::Test
+  def setup
+    @app = ->(_request) { { jsonrpc: "2.0", id: 1, result: "success" } }
+    @middleware = AuthenticationMiddleware.new(@app, 
+                                             secret_key: "test_secret",
+                                             required_methods: ["tools/call"])
+  end
+  
+  def test_allows_unauthenticated_methods
+    request = {
+      "jsonrpc" => "2.0",
+      "id" => 1,
+      "method" => "initialize"
+    }
+    
+    response = @middleware.call(request)
+    assert_equal "success", response[:result]
+  end
+  
+  def test_requires_auth_for_tools
+    request = {
+      "jsonrpc" => "2.0",
+      "id" => 1,
+      "method" => "tools/call"
+    }
+    
+    response = @middleware.call(request)
+    assert_equal -32001, response[:error][:code]
+    assert_equal "Unauthorized", response[:error][:message]
+  end
+  
+  def test_accepts_valid_token
+    token = generate_valid_token
+    request = {
+      "jsonrpc" => "2.0",
+      "id" => 1,
+      "method" => "tools/call",
+      "params" => { "_token" => token }
+    }
+    
+    response = @middleware.call(request)
+    assert_equal "success", response[:result]
+  end
+  
+  private
+  
+  def generate_valid_token
+    payload = {
+      user_id: 123,
+      exp: Time.now.to_i + 3600
+    }
+    JWT.encode(payload, "test_secret", 'HS256')
+  end
+end
+```
+
+### Testing Rate Limiting
+
+```ruby
+class RateLimitTest < Minitest::Test
+  def setup
+    @app = ->(_request) { { jsonrpc: "2.0", id: 1, result: "success" } }
+    @middleware = Tsikol::RateLimitMiddleware.new(@app,
+                                                  max_requests: 3,
+                                                  window_seconds: 1)
+  end
+  
+  def test_allows_requests_under_limit
+    3.times do |i|
+      request = { "jsonrpc" => "2.0", "id" => i, "method" => "test" }
+      response = @middleware.call(request)
+      assert_equal "success", response[:result]
+    end
+  end
+  
+  def test_blocks_requests_over_limit
+    # Make max requests
+    3.times do |i|
+      request = { "jsonrpc" => "2.0", "id" => i, "method" => "test" }
+      @middleware.call(request)
+    end
+    
+    # Next request should be rate limited
+    request = { "jsonrpc" => "2.0", "id" => 4, "method" => "test" }
+    response = @middleware.call(request)
+    
+    assert response[:error]
+    assert_match /rate limit/i, response[:error][:message]
+  end
+  
+  def test_resets_after_window
+    # Make max requests
+    3.times { |i| @middleware.call(base_request(i)) }
+    
+    # Wait for window to reset
+    sleep(1.1)
+    
+    # Should allow new requests
+    response = @middleware.call(base_request(4))
+    assert_equal "success", response[:result]
+  end
+  
+  private
+  
+  def base_request(id)
+    { "jsonrpc" => "2.0", "id" => id, "method" => "test" }
+  end
+end
+```
+
+## Best Practices
+
+1. **Keep Middleware Focused**: Each middleware should have one responsibility
+2. **Order Matters**: Place auth before rate limiting, logging first/last
+3. **Handle Errors**: Don't let middleware errors crash the server
+4. **Performance**: Middleware runs on every request, keep it fast
+5. **Thread Safety**: Ensure middleware is thread-safe
+6. **Configuration**: Make middleware configurable via options
+7. **Testing**: Test middleware in isolation and integration
+
+## Common Middleware Stack
+
+A typical production middleware stack:
+
+```ruby
+Tsikol.server "production-server" do
+  # Observability
+  use Tsikol::LoggingMiddleware, level: :info
+  use Tsikol::MetricsMiddleware
+  
+  # Security
+  use ValidationMiddleware, max_request_size: 5_242_880  # 5MB
+  use AuthenticationMiddleware, secret_key: ENV['SECRET_KEY']
+  
+  # Protection
+  use Tsikol::RateLimitMiddleware, max_requests: 1000, window_seconds: 60
+  use CircuitBreakerMiddleware, failure_threshold: 10
+  
+  # Performance
+  use CachingMiddleware, ttl: 300
+  
+  # Error handling (last)
+  use Tsikol::ErrorHandlingMiddleware, log_errors: true
+  
+  # Your application
+  tool FileManager
+  resource SystemStatus
+  prompt Assistant
+end
+```
+
+## Next Steps
+
+- Learn about [Testing](testing.md)
+- Implement [Authentication](../cookbook/authentication.md)
+- Add [Rate Limiting](../cookbook/rate-limiting.md)
+- Set up [Logging](../cookbook/logging.md)