tsikol 0.1.0

data/docs/api/middleware.md

@@ -0,0 +1,721 @@
+# Middleware API Reference
+
+The `Tsikol::Middleware` class provides the foundation for creating middleware components that intercept and process requests/responses.
+
+## Class: Tsikol::Middleware
+
+### Constructor
+
+```ruby
+class MyMiddleware < Tsikol::Middleware
+  def initialize(app, options = {})
+    @app = app
+    @options = options
+    # Additional initialization
+  end
+end
+```
+
+#### Parameters
+
+- `app`: The next middleware or handler in the chain
+- `options` (Hash): Configuration options for the middleware
+
+### Core Method
+
+#### `#call(request)`
+
+Process a request and optionally modify the response.
+
+```ruby
+def call(request)
+  # Before request processing
+  modified_request = process_request(request)
+  
+  # Call next middleware/handler
+  response = @app.call(modified_request)
+  
+  # After response processing
+  process_response(response)
+end
+```
+
+## Built-in Middleware
+
+### Tsikol::LoggingMiddleware
+
+Logs all requests and responses.
+
+```ruby
+server.use Tsikol::LoggingMiddleware, 
+  level: :info,              # Log level (:debug, :info, :warning, :error)
+  include_params: true,      # Log request parameters
+  include_response: true,    # Log response data
+  max_response_length: 1000  # Truncate long responses
+```
+
+Example implementation:
+
+```ruby
+class LoggingMiddleware < Tsikol::Middleware
+  def initialize(app, options = {})
+    super
+    @level = options[:level] || :info
+    @include_params = options.fetch(:include_params, true)
+    @include_response = options.fetch(:include_response, true)
+    @max_response_length = options[:max_response_length] || 1000
+  end
+  
+  def call(request)
+    start_time = Time.now
+    request_id = request["id"]
+    method = request["method"]
+    
+    # Log request
+    log_data = { method: method, id: request_id }
+    log_data[:params] = request["params"] if @include_params && request["params"]
+    
+    log @level, "Request received", log_data
+    
+    # Process request
+    response = @app.call(request)
+    
+    # Log response
+    duration = ((Time.now - start_time) * 1000).round(2)
+    
+    response_data = { 
+      method: method, 
+      id: request_id, 
+      duration_ms: duration,
+      status: response[:error] ? "error" : "success"
+    }
+    
+    if @include_response
+      if response[:error]
+        response_data[:error] = response[:error]
+      elsif response[:result]
+        result_str = response[:result].to_s
+        if result_str.length > @max_response_length
+          response_data[:result] = result_str[0...@max_response_length] + "..."
+          response_data[:truncated] = true
+        else
+          response_data[:result] = response[:result]
+        end
+      end
+    end
+    
+    log @level, "Request completed", response_data
+    
+    response
+  rescue => e
+    log :error, "Request failed", 
+        method: method, 
+        id: request_id,
+        error: e.class.name,
+        message: e.message
+    raise
+  end
+  
+  private
+  
+  def log(level, message, data)
+    return unless @app.respond_to?(:log)
+    @app.log(level, message, data: data)
+  end
+end
+```
+
+### Tsikol::ErrorHandlingMiddleware
+
+Provides consistent error handling and formatting.
+
+```ruby
+server.use Tsikol::ErrorHandlingMiddleware,
+  log_errors: true,           # Log errors
+  include_backtrace: false,   # Include stack traces in development
+  error_handler: ->(e) { }    # Custom error handler callback
+```
+
+Example implementation:
+
+```ruby
+class ErrorHandlingMiddleware < Tsikol::Middleware
+  def initialize(app, options = {})
+    super
+    @log_errors = options.fetch(:log_errors, true)
+    @include_backtrace = options.fetch(:include_backtrace, false)
+    @error_handler = options[:error_handler]
+  end
+  
+  def call(request)
+    @app.call(request)
+  rescue Tsikol::ValidationError => e
+    handle_validation_error(request, e)
+  rescue Tsikol::NotFoundError => e
+    handle_not_found_error(request, e)
+  rescue StandardError => e
+    handle_internal_error(request, e)
+  end
+  
+  private
+  
+  def handle_validation_error(request, error)
+    log_error(request, error) if @log_errors
+    
+    {
+      jsonrpc: "2.0",
+      id: request["id"],
+      error: {
+        code: -32602,
+        message: "Invalid params",
+        data: { details: error.message }
+      }
+    }
+  end
+  
+  def handle_not_found_error(request, error)
+    log_error(request, error) if @log_errors
+    
+    {
+      jsonrpc: "2.0",
+      id: request["id"],
+      error: {
+        code: -32601,
+        message: "Method not found",
+        data: { details: error.message }
+      }
+    }
+  end
+  
+  def handle_internal_error(request, error)
+    log_error(request, error) if @log_errors
+    @error_handler&.call(error)
+    
+    error_data = { message: error.message }
+    error_data[:backtrace] = error.backtrace.first(10) if @include_backtrace
+    
+    {
+      jsonrpc: "2.0",
+      id: request["id"],
+      error: {
+        code: -32603,
+        message: "Internal error",
+        data: error_data
+      }
+    }
+  end
+  
+  def log_error(request, error)
+    return unless @app.respond_to?(:log)
+    
+    @app.log :error, "Request error",
+             data: {
+               method: request["method"],
+               error_class: error.class.name,
+               error_message: error.message,
+               backtrace: error.backtrace&.first(5)
+             }
+  end
+end
+```
+
+### Tsikol::RateLimitMiddleware
+
+Implements rate limiting to prevent abuse.
+
+```ruby
+server.use Tsikol::RateLimitMiddleware,
+  max_requests: 100,        # Maximum requests per window
+  window_seconds: 60,       # Time window in seconds
+  by: :client_id,          # Group requests by this key
+  skip_methods: []         # Methods to exclude from rate limiting
+```
+
+Example implementation:
+
+```ruby
+class RateLimitMiddleware < Tsikol::Middleware
+  def initialize(app, options = {})
+    super
+    @max_requests = options[:max_requests] || 60
+    @window_seconds = options[:window_seconds] || 60
+    @by = options[:by] || :client_id
+    @skip_methods = options[:skip_methods] || []
+    @buckets = {}
+    @mutex = Mutex.new
+  end
+  
+  def call(request)
+    method = request["method"]
+    
+    # Skip rate limiting for certain methods
+    return @app.call(request) if @skip_methods.include?(method)
+    
+    # Get client identifier
+    client_id = get_client_id(request)
+    
+    # Check rate limit
+    if rate_limited?(client_id)
+      return rate_limit_response(request)
+    end
+    
+    # Track request
+    track_request(client_id)
+    
+    # Process request
+    @app.call(request)
+  end
+  
+  private
+  
+  def get_client_id(request)
+    case @by
+    when :client_id
+      request.dig("params", "_client_id") || "anonymous"
+    when :ip
+      request.dig("meta", "remote_ip") || "unknown"
+    when Proc
+      @by.call(request)
+    else
+      "global"
+    end
+  end
+  
+  def rate_limited?(client_id)
+    @mutex.synchronize do
+      bucket = get_bucket(client_id)
+      clean_bucket(bucket)
+      bucket[:requests].size >= @max_requests
+    end
+  end
+  
+  def track_request(client_id)
+    @mutex.synchronize do
+      bucket = get_bucket(client_id)
+      bucket[:requests] << Time.now
+    end
+  end
+  
+  def get_bucket(client_id)
+    @buckets[client_id] ||= { requests: [] }
+  end
+  
+  def clean_bucket(bucket)
+    cutoff = Time.now - @window_seconds
+    bucket[:requests].reject! { |time| time < cutoff }
+  end
+  
+  def rate_limit_response(request)
+    {
+      jsonrpc: "2.0",
+      id: request["id"],
+      error: {
+        code: -32000,
+        message: "Rate limit exceeded",
+        data: {
+          max_requests: @max_requests,
+          window_seconds: @window_seconds,
+          retry_after: @window_seconds
+        }
+      }
+    }
+  end
+end
+```
+
+### Tsikol::MetricsMiddleware
+
+Collects performance metrics.
+
+```ruby
+server.use Tsikol::MetricsMiddleware,
+  include_histogram: true,    # Track response time distribution
+  track_errors: true,         # Count errors by type
+  custom_tags: {}            # Additional tags for metrics
+```
+
+## Creating Custom Middleware
+
+### Basic Template
+
+```ruby
+class CustomMiddleware < Tsikol::Middleware
+  def initialize(app, options = {})
+    @app = app
+    # Initialize with options
+  end
+  
+  def call(request)
+    # Pre-processing
+    
+    # Call next middleware
+    response = @app.call(request)
+    
+    # Post-processing
+    
+    response
+  end
+end
+```
+
+### Request Modification
+
+```ruby
+class RequestEnrichmentMiddleware < Tsikol::Middleware
+  def call(request)
+    # Add metadata
+    request["meta"] ||= {}
+    request["meta"]["timestamp"] = Time.now.iso8601
+    request["meta"]["request_id"] = SecureRandom.uuid
+    
+    # Add default parameters
+    if request["params"]
+      request["params"]["_server_version"] = Tsikol::VERSION
+    end
+    
+    @app.call(request)
+  end
+end
+```
+
+### Response Modification
+
+```ruby
+class ResponseFormattingMiddleware < Tsikol::Middleware
+  def call(request)
+    start_time = Time.now
+    
+    response = @app.call(request)
+    
+    # Add timing information
+    duration = Time.now - start_time
+    
+    if response[:result]
+      response[:result] = {
+        data: response[:result],
+        meta: {
+          duration_seconds: duration,
+          timestamp: Time.now.iso8601
+        }
+      }
+    end
+    
+    response
+  end
+end
+```
+
+### Conditional Processing
+
+```ruby
+class ConditionalMiddleware < Tsikol::Middleware
+  def initialize(app, options = {})
+    super
+    @condition = options[:if] || ->(_) { true }
+    @unless = options[:unless] || ->(_) { false }
+  end
+  
+  def call(request)
+    if should_process?(request)
+      # Apply middleware logic
+      process_with_middleware(request)
+    else
+      # Skip middleware
+      @app.call(request)
+    end
+  end
+  
+  private
+  
+  def should_process?(request)
+    @condition.call(request) && !@unless.call(request)
+  end
+  
+  def process_with_middleware(request)
+    # Middleware logic here
+    @app.call(request)
+  end
+end
+```
+
+### Short-Circuit Responses
+
+```ruby
+class CacheMiddleware < Tsikol::Middleware
+  def initialize(app, options = {})
+    super
+    @cache = {}
+    @ttl = options[:ttl] || 300
+  end
+  
+  def call(request)
+    # Only cache certain methods
+    return @app.call(request) unless cacheable?(request)
+    
+    cache_key = generate_key(request)
+    
+    # Check cache
+    if cached = get_cached(cache_key)
+      # Return cached response without calling app
+      return cached
+    end
+    
+    # Process and cache
+    response = @app.call(request)
+    
+    if response[:result]
+      set_cached(cache_key, response)
+    end
+    
+    response
+  end
+  
+  private
+  
+  def cacheable?(request)
+    ["resources/read", "prompts/get"].include?(request["method"])
+  end
+  
+  def generate_key(request)
+    "#{request['method']}:#{request['params'].to_json}"
+  end
+  
+  def get_cached(key)
+    entry = @cache[key]
+    return nil unless entry
+    return nil if Time.now - entry[:time] > @ttl
+    entry[:response]
+  end
+  
+  def set_cached(key, response)
+    @cache[key] = {
+      response: response,
+      time: Time.now
+    }
+  end
+end
+```
+
+## Middleware Composition
+
+### Combining Middleware
+
+```ruby
+class CompositeMiddleware < Tsikol::Middleware
+  def initialize(app, *middleware_classes)
+    @app = build_chain(app, middleware_classes)
+  end
+  
+  def call(request)
+    @app.call(request)
+  end
+  
+  private
+  
+  def build_chain(app, middleware_classes)
+    middleware_classes.reverse.reduce(app) do |next_app, (klass, options)|
+      klass.new(next_app, options || {})
+    end
+  end
+end
+
+# Usage
+server.use CompositeMiddleware,
+  [LoggingMiddleware, { level: :debug }],
+  [RateLimitMiddleware, { max_requests: 100 }],
+  [CacheMiddleware, { ttl: 600 }]
+```
+
+### Middleware Stack
+
+```ruby
+class MiddlewareStack
+  def initialize
+    @middlewares = []
+  end
+  
+  def use(middleware_class, options = {})
+    @middlewares << [middleware_class, options]
+  end
+  
+  def build(app)
+    @middlewares.reverse.reduce(app) do |next_app, (klass, opts)|
+      klass.new(next_app, opts)
+    end
+  end
+end
+```
+
+## Testing Middleware
+
+### Basic Middleware Test
+
+```ruby
+require 'minitest/autorun'
+
+class MiddlewareTest < Minitest::Test
+  def setup
+    @app = MockApp.new
+    @middleware = MyMiddleware.new(@app, option: "value")
+  end
+  
+  def test_passes_request_through
+    request = build_request("test.method")
+    response = @middleware.call(request)
+    
+    assert_equal "success", response[:result]
+    assert @app.called_with?(request)
+  end
+  
+  def test_modifies_request
+    request = build_request("test.method")
+    @middleware.call(request)
+    
+    # Check that middleware modified the request
+    assert request["meta"]["added_by_middleware"]
+  end
+  
+  def test_handles_app_errors
+    @app.raise_error = true
+    request = build_request("test.method")
+    
+    assert_raises(StandardError) do
+      @middleware.call(request)
+    end
+  end
+  
+  private
+  
+  def build_request(method, params = {})
+    {
+      "jsonrpc" => "2.0",
+      "id" => 1,
+      "method" => method,
+      "params" => params
+    }
+  end
+end
+
+class MockApp
+  attr_accessor :raise_error
+  attr_reader :last_request
+  
+  def call(request)
+    @last_request = request
+    raise StandardError, "Mock error" if raise_error
+    { jsonrpc: "2.0", id: request["id"], result: "success" }
+  end
+  
+  def called_with?(request)
+    @last_request == request
+  end
+end
+```
+
+### Integration Testing
+
+```ruby
+class MiddlewareIntegrationTest < Minitest::Test
+  def setup
+    @server = Tsikol::Server.new(name: "test")
+    
+    # Add middleware stack
+    @server.use TimingMiddleware
+    @server.use LoggingMiddleware, level: :debug
+    @server.use ErrorHandlingMiddleware
+    
+    # Add a test tool
+    @server.register_tool("echo") do |message:|
+      message
+    end
+  end
+  
+  def test_middleware_chain_execution_order
+    # Create a tracking middleware
+    call_order = []
+    
+    tracking_middleware = Class.new(Tsikol::Middleware) do
+      define_method :initialize do |app, name:|
+        @app = app
+        @name = name
+      end
+      
+      define_method :call do |request|
+        call_order << "#{@name}:before"
+        response = @app.call(request)
+        call_order << "#{@name}:after"
+        response
+      end
+    end
+    
+    server = Tsikol::Server.new(name: "test")
+    server.use tracking_middleware, name: "first"
+    server.use tracking_middleware, name: "second"
+    server.use tracking_middleware, name: "third"
+    
+    server.handle_request({
+      "jsonrpc" => "2.0",
+      "id" => 1,
+      "method" => "initialize"
+    })
+    
+    # Verify execution order
+    expected = [
+      "first:before",
+      "second:before", 
+      "third:before",
+      "third:after",
+      "second:after",
+      "first:after"
+    ]
+    
+    assert_equal expected, call_order
+  end
+end
+```
+
+## Thread Safety
+
+Middleware should be thread-safe:
+
+```ruby
+class ThreadSafeMiddleware < Tsikol::Middleware
+  def initialize(app, options = {})
+    super
+    @mutex = Mutex.new
+    @counter = 0
+  end
+  
+  def call(request)
+    # Thread-safe increment
+    @mutex.synchronize { @counter += 1 }
+    
+    # Process request
+    response = @app.call(request)
+    
+    # Thread-safe operation
+    @mutex.synchronize do
+      # Critical section
+    end
+    
+    response
+  end
+end
+```
+
+## Best Practices
+
+1. **Single Responsibility**: Each middleware should have one clear purpose
+2. **Minimize Overhead**: Middleware runs on every request, keep it efficient
+3. **Error Handling**: Always handle errors gracefully, don't swallow exceptions
+4. **Thread Safety**: Ensure middleware is thread-safe for concurrent requests
+5. **Configuration**: Make middleware configurable through options
+6. **Logging**: Use appropriate log levels and don't log sensitive data
+7. **Testing**: Test middleware in isolation and as part of the stack
+
+## See Also
+
+- [Middleware Guide](../guides/middleware.md)
+- [Server API](server.md)
+- [Error Handling](../cookbook/error-handling.md)
+- [Testing Guide](../guides/testing.md)