tsikol 0.1.0

data/docs/cookbook/caching.md

@@ -0,0 +1,877 @@
+# Caching Recipe
+
+This recipe shows various caching strategies to improve performance and reduce load on your MCP server.
+
+## Basic In-Memory Caching
+
+### Simple Cache for Tools
+
+```ruby
+class CachedTool < Tsikol::Tool
+  def initialize
+    super
+    @cache = {}
+    @cache_ttl = 300  # 5 minutes
+  end
+  
+  parameter :query do
+    type :string
+    required
+    description "Query to process"
+  end
+  
+  def execute(query:)
+    cache_key = generate_cache_key(query)
+    
+    # Check cache
+    if cached = get_cached(cache_key)
+      log :debug, "Cache hit", key: cache_key
+      return cached[:value]
+    end
+    
+    # Cache miss - compute result
+    log :debug, "Cache miss", key: cache_key
+    result = expensive_computation(query)
+    
+    # Store in cache
+    set_cached(cache_key, result)
+    
+    result
+  end
+  
+  private
+  
+  def generate_cache_key(query)
+    Digest::SHA256.hexdigest(query)
+  end
+  
+  def get_cached(key)
+    entry = @cache[key]
+    return nil unless entry
+    
+    # Check if expired
+    if Time.now - entry[:cached_at] > @cache_ttl
+      @cache.delete(key)
+      return nil
+    end
+    
+    entry
+  end
+  
+  def set_cached(key, value)
+    @cache[key] = {
+      value: value,
+      cached_at: Time.now
+    }
+    
+    # Limit cache size
+    cleanup_cache if @cache.size > 1000
+  end
+  
+  def cleanup_cache
+    # Remove oldest entries
+    sorted = @cache.sort_by { |_, v| v[:cached_at] }
+    sorted.first(@cache.size - 800).each { |k, _| @cache.delete(k) }
+  end
+  
+  def expensive_computation(query)
+    # Simulate expensive operation
+    sleep(0.5)
+    "Result for: #{query}"
+  end
+end
+```
+
+### Thread-Safe Memory Cache
+
+```ruby
+require 'concurrent'
+
+class ThreadSafeCache
+  def initialize(options = {})
+    @max_size = options[:max_size] || 1000
+    @ttl = options[:ttl] || 300
+    @cache = Concurrent::Map.new
+    @access_count = Concurrent::Map.new
+    @last_cleanup = Concurrent::AtomicReference.new(Time.now)
+  end
+  
+  def fetch(key, &block)
+    # Try to get from cache
+    if entry = @cache[key]
+      if valid_entry?(entry)
+        track_access(key)
+        return entry[:value]
+      else
+        @cache.delete(key)
+      end
+    end
+    
+    # Cache miss - compute value
+    value = yield
+    
+    # Store in cache
+    @cache[key] = {
+      value: value,
+      cached_at: Time.now,
+      ttl: @ttl
+    }
+    
+    # Cleanup if needed
+    cleanup if should_cleanup?
+    
+    value
+  end
+  
+  def clear
+    @cache.clear
+    @access_count.clear
+  end
+  
+  def size
+    @cache.size
+  end
+  
+  def stats
+    {
+      size: @cache.size,
+      max_size: @max_size,
+      access_counts: @access_count.each_pair.to_h
+    }
+  end
+  
+  private
+  
+  def valid_entry?(entry)
+    Time.now - entry[:cached_at] <= entry[:ttl]
+  end
+  
+  def track_access(key)
+    @access_count.compute(key) { |old| (old || 0) + 1 }
+  end
+  
+  def should_cleanup?
+    @cache.size > @max_size || 
+      (Time.now - @last_cleanup.get > 60)  # Cleanup every minute
+  end
+  
+  def cleanup
+    return unless @last_cleanup.compare_and_set(@last_cleanup.get, Time.now)
+    
+    # Remove expired entries
+    @cache.each_pair do |key, entry|
+      @cache.delete(key) unless valid_entry?(entry)
+    end
+    
+    # If still over size, remove least accessed
+    if @cache.size > @max_size
+      entries_to_remove = @cache.size - (@max_size * 0.8).to_i
+      
+      sorted = @cache.keys.sort_by { |k| @access_count[k] || 0 }
+      sorted.first(entries_to_remove).each do |key|
+        @cache.delete(key)
+        @access_count.delete(key)
+      end
+    end
+  end
+end
+
+# Usage in tools
+class CachedDatabaseTool < Tsikol::Tool
+  def initialize
+    super
+    @cache = ThreadSafeCache.new(max_size: 500, ttl: 600)
+  end
+  
+  def execute(query:)
+    @cache.fetch(query) do
+      # Expensive database query
+      perform_database_query(query)
+    end
+  end
+end
+```
+
+## Caching Middleware
+
+### Request/Response Cache
+
+```ruby
+class CachingMiddleware < Tsikol::Middleware
+  def initialize(app, options = {})
+    @app = app
+    @cache = ThreadSafeCache.new(options)
+    @cacheable_methods = options[:cacheable_methods] || default_cacheable_methods
+    @cache_key_generator = options[:cache_key_generator] || method(:default_cache_key)
+  end
+  
+  def call(request)
+    return @app.call(request) unless cacheable?(request)
+    
+    cache_key = @cache_key_generator.call(request)
+    
+    @cache.fetch(cache_key) do
+      log :debug, "Cache miss", method: request["method"], key: cache_key
+      
+      response = @app.call(request)
+      
+      # Only cache successful responses
+      if response[:result] && !response[:error]
+        response
+      else
+        # Don't cache errors, but return them
+        throw :cache_skip, response
+      end
+    end
+  rescue UncaughtThrowError => e
+    e.value  # Return the response that was thrown
+  end
+  
+  private
+  
+  def default_cacheable_methods
+    [
+      "resources/read",      # Resources are good cache candidates
+      "prompts/get",        # Prompts rarely change
+      "completion/complete" # Completions for same input
+    ]
+  end
+  
+  def cacheable?(request)
+    @cacheable_methods.include?(request["method"])
+  end
+  
+  def default_cache_key(request)
+    # Include method and parameters in cache key
+    data = {
+      method: request["method"],
+      params: normalize_params(request["params"])
+    }
+    
+    Digest::SHA256.hexdigest(data.to_json)
+  end
+  
+  def normalize_params(params)
+    # Sort hash keys for consistent cache keys
+    return params unless params.is_a?(Hash)
+    
+    params.sort.to_h.transform_values do |value|
+      value.is_a?(Hash) ? normalize_params(value) : value
+    end
+  end
+end
+```
+
+### Selective Cache Invalidation
+
+```ruby
+class SmartCachingMiddleware < CachingMiddleware
+  def initialize(app, options = {})
+    super
+    @invalidation_rules = options[:invalidation_rules] || default_invalidation_rules
+    @cache_dependencies = Concurrent::Map.new
+  end
+  
+  def call(request)
+    # Check if this request should invalidate cache
+    if should_invalidate?(request)
+      invalidate_related_cache(request)
+    end
+    
+    # Normal caching logic
+    super
+  end
+  
+  private
+  
+  def default_invalidation_rules
+    {
+      "tools/call" => ->(request) {
+        # Invalidate cache when certain tools are called
+        tool_name = request.dig("params", "name")
+        case tool_name
+        when "update_config"
+          ["resources/read:config/*"]
+        when "clear_cache"
+          ["*"]  # Clear everything
+        else
+          []
+        end
+      }
+    }
+  end
+  
+  def should_invalidate?(request)
+    @invalidation_rules.key?(request["method"])
+  end
+  
+  def invalidate_related_cache(request)
+    rule = @invalidation_rules[request["method"]]
+    patterns = rule.call(request)
+    
+    patterns.each do |pattern|
+      if pattern == "*"
+        @cache.clear
+        log :info, "Cache cleared"
+      else
+        invalidate_pattern(pattern)
+      end
+    end
+  end
+  
+  def invalidate_pattern(pattern)
+    # Simple pattern matching
+    @cache.each_key do |key|
+      if key_matches_pattern?(key, pattern)
+        @cache.delete(key)
+        log :debug, "Cache invalidated", key: key, pattern: pattern
+      end
+    end
+  end
+end
+```
+
+## Redis-Based Caching
+
+### Distributed Cache
+
+```ruby
+require 'redis'
+require 'json'
+
+class RedisCache
+  def initialize(options = {})
+    @redis = options[:redis] || Redis.new
+    @ttl = options[:ttl] || 300
+    @prefix = options[:prefix] || "mcp:cache"
+    @compress = options[:compress] || false
+    @compress_threshold = options[:compress_threshold] || 1024  # bytes
+  end
+  
+  def fetch(key, ttl: @ttl)
+    redis_key = make_key(key)
+    
+    # Try to get from cache
+    if cached = @redis.get(redis_key)
+      return deserialize(cached)
+    end
+    
+    # Cache miss - compute value
+    value = yield
+    
+    # Store in cache
+    set(key, value, ttl: ttl)
+    
+    value
+  end
+  
+  def get(key)
+    redis_key = make_key(key)
+    cached = @redis.get(redis_key)
+    deserialize(cached) if cached
+  end
+  
+  def set(key, value, ttl: @ttl)
+    redis_key = make_key(key)
+    serialized = serialize(value)
+    
+    if ttl > 0
+      @redis.setex(redis_key, ttl, serialized)
+    else
+      @redis.set(redis_key, serialized)
+    end
+  end
+  
+  def delete(key)
+    redis_key = make_key(key)
+    @redis.del(redis_key)
+  end
+  
+  def clear_pattern(pattern)
+    redis_pattern = make_key(pattern)
+    
+    # Use SCAN to avoid blocking on large datasets
+    cursor = 0
+    loop do
+      cursor, keys = @redis.scan(cursor, match: redis_pattern, count: 100)
+      @redis.del(*keys) unless keys.empty?
+      break if cursor == "0"
+    end
+  end
+  
+  private
+  
+  def make_key(key)
+    "#{@prefix}:#{key}"
+  end
+  
+  def serialize(value)
+    json = value.to_json
+    
+    if @compress && json.bytesize > @compress_threshold
+      compressed = Zlib.deflate(json)
+      "gzip:#{Base64.strict_encode64(compressed)}"
+    else
+      json
+    end
+  end
+  
+  def deserialize(data)
+    if data.start_with?("gzip:")
+      compressed = Base64.strict_decode64(data[5..-1])
+      json = Zlib.inflate(compressed)
+    else
+      json = data
+    end
+    
+    JSON.parse(json)
+  end
+end
+
+# Redis caching middleware
+class RedisCachingMiddleware < Tsikol::Middleware
+  def initialize(app, options = {})
+    @app = app
+    @cache = RedisCache.new(options)
+    @cacheable_methods = options[:cacheable_methods] || []
+  end
+  
+  def call(request)
+    return @app.call(request) unless cacheable?(request)
+    
+    cache_key = generate_cache_key(request)
+    ttl = determine_ttl(request)
+    
+    @cache.fetch(cache_key, ttl: ttl) do
+      response = @app.call(request)
+      
+      # Only cache successful responses
+      response if response[:result]
+    end || @app.call(request)  # Fallback if caching fails
+  end
+  
+  private
+  
+  def determine_ttl(request)
+    case request["method"]
+    when "resources/read"
+      # Resources might change less frequently
+      600  # 10 minutes
+    when "completion/complete"
+      # Completions are more stable
+      3600  # 1 hour
+    else
+      300  # 5 minutes default
+    end
+  end
+end
+```
+
+## Content-Based Caching
+
+### ETags and Conditional Requests
+
+```ruby
+class ETagResource < Tsikol::Resource
+  def read
+    content = generate_content
+    etag = generate_etag(content)
+    
+    # Check if client has matching ETag
+    if client_etag == etag
+      return not_modified_response
+    end
+    
+    # Return content with ETag
+    {
+      content: content,
+      etag: etag,
+      last_modified: last_modified_time
+    }.to_json
+  end
+  
+  private
+  
+  def generate_etag(content)
+    Digest::MD5.hexdigest(content)
+  end
+  
+  def client_etag
+    # In real implementation, extract from request headers
+    Thread.current[:mcp_request]&.dig("params", "if_none_match")
+  end
+  
+  def not_modified_response
+    {
+      status: 304,
+      message: "Not Modified",
+      etag: etag
+    }.to_json
+  end
+  
+  def last_modified_time
+    # Track when content actually changes
+    @last_modified ||= Time.now
+  end
+end
+```
+
+### Cache Warming
+
+```ruby
+class CacheWarmer
+  def initialize(server, options = {})
+    @server = server
+    @cache = options[:cache]
+    @warmup_paths = options[:warmup_paths] || []
+    @interval = options[:interval] || 300  # 5 minutes
+  end
+  
+  def start
+    Thread.new do
+      loop do
+        warm_cache
+        sleep @interval
+      end
+    end
+  end
+  
+  def warm_cache
+    @warmup_paths.each do |path|
+      begin
+        case path[:type]
+        when :resource
+          warm_resource(path[:uri])
+        when :tool
+          warm_tool(path[:name], path[:params])
+        end
+      rescue => e
+        log :error, "Cache warming failed", path: path, error: e.message
+      end
+    end
+  end
+  
+  private
+  
+  def warm_resource(uri)
+    request = {
+      "jsonrpc" => "2.0",
+      "id" => "cache_warm_#{Time.now.to_i}",
+      "method" => "resources/read",
+      "params" => { "uri" => uri }
+    }
+    
+    response = @server.handle_request(request)
+    log :debug, "Warmed resource cache", uri: uri
+  end
+  
+  def warm_tool(name, params)
+    request = {
+      "jsonrpc" => "2.0",
+      "id" => "cache_warm_#{Time.now.to_i}",
+      "method" => "tools/call",
+      "params" => { "name" => name, "arguments" => params }
+    }
+    
+    response = @server.handle_request(request)
+    log :debug, "Warmed tool cache", tool: name
+  end
+end
+
+# Usage
+Tsikol.start(name: "cached-server") do
+  cache = RedisCache.new
+  
+  # Add caching middleware
+  use RedisCachingMiddleware, 
+      cache: cache,
+      cacheable_methods: ["resources/read", "tools/call"]
+  
+  # Start cache warmer
+  after_start do
+    warmer = CacheWarmer.new(self,
+      cache: cache,
+      warmup_paths: [
+        { type: :resource, uri: "config" },
+        { type: :resource, uri: "system/status" },
+        { type: :tool, name: "popular_query", params: { query: "common" } }
+      ]
+    )
+    warmer.start
+  end
+  
+  # Your components
+  resource ConfigResource
+  tool QueryTool
+end
+```
+
+## Cache Strategies
+
+### Write-Through Cache
+
+```ruby
+class WriteThroughCache
+  def initialize(cache, data_source)
+    @cache = cache
+    @data_source = data_source
+  end
+  
+  def read(key)
+    @cache.fetch(key) do
+      @data_source.read(key)
+    end
+  end
+  
+  def write(key, value)
+    # Write to data source first
+    @data_source.write(key, value)
+    
+    # Then update cache
+    @cache.set(key, value)
+    
+    value
+  end
+  
+  def delete(key)
+    # Delete from data source
+    @data_source.delete(key)
+    
+    # Then remove from cache
+    @cache.delete(key)
+  end
+end
+```
+
+### Write-Behind Cache
+
+```ruby
+class WriteBehindCache
+  def initialize(cache, data_source, options = {})
+    @cache = cache
+    @data_source = data_source
+    @write_delay = options[:write_delay] || 5
+    @batch_size = options[:batch_size] || 100
+    @write_queue = Queue.new
+    
+    start_write_thread
+  end
+  
+  def read(key)
+    # Check write queue first
+    if pending = check_write_queue(key)
+      return pending
+    end
+    
+    @cache.fetch(key) do
+      @data_source.read(key)
+    end
+  end
+  
+  def write(key, value)
+    # Update cache immediately
+    @cache.set(key, value)
+    
+    # Queue for later write
+    @write_queue << { key: key, value: value, time: Time.now }
+    
+    value
+  end
+  
+  private
+  
+  def start_write_thread
+    Thread.new do
+      loop do
+        batch = []
+        
+        # Collect writes for batch
+        deadline = Time.now + @write_delay
+        while Time.now < deadline && batch.size < @batch_size
+          begin
+            item = @write_queue.pop(timeout: deadline - Time.now)
+            batch << item if item
+          rescue ThreadError
+            # Timeout - process what we have
+            break
+          end
+        end
+        
+        # Write batch to data source
+        write_batch(batch) unless batch.empty?
+      end
+    end
+  end
+  
+  def write_batch(batch)
+    @data_source.write_batch(batch)
+  rescue => e
+    log :error, "Write-behind failed", error: e.message
+    # Re-queue failed writes
+    batch.each { |item| @write_queue << item }
+  end
+end
+```
+
+## Cache Monitoring
+
+```ruby
+class CacheMetrics
+  def initialize(cache)
+    @cache = cache
+    @hits = Concurrent::AtomicFixnum.new(0)
+    @misses = Concurrent::AtomicFixnum.new(0)
+    @errors = Concurrent::AtomicFixnum.new(0)
+    @total_time = Concurrent::AtomicFixnum.new(0)
+  end
+  
+  def track_fetch(key)
+    start = Time.now
+    hit = false
+    
+    begin
+      value = yield
+      hit = !value.nil?
+      value
+    rescue => e
+      @errors.increment
+      raise
+    ensure
+      duration = ((Time.now - start) * 1000).to_i
+      @total_time.add(duration)
+      
+      if hit
+        @hits.increment
+      else
+        @misses.increment
+      end
+    end
+  end
+  
+  def stats
+    total = @hits.value + @misses.value
+    hit_rate = total > 0 ? (@hits.value.to_f / total * 100).round(2) : 0
+    avg_time = total > 0 ? (@total_time.value.to_f / total).round(2) : 0
+    
+    {
+      hits: @hits.value,
+      misses: @misses.value,
+      hit_rate: hit_rate,
+      errors: @errors.value,
+      avg_response_time_ms: avg_time,
+      cache_size: @cache.size
+    }
+  end
+end
+
+# Monitored cache middleware
+class MonitoredCachingMiddleware < CachingMiddleware
+  def initialize(app, options = {})
+    super
+    @metrics = CacheMetrics.new(@cache)
+  end
+  
+  def call(request)
+    if request["method"] == "cache/stats"
+      return cache_stats_response(request["id"])
+    end
+    
+    return @app.call(request) unless cacheable?(request)
+    
+    cache_key = @cache_key_generator.call(request)
+    
+    @metrics.track_fetch(cache_key) do
+      @cache.fetch(cache_key) do
+        @app.call(request)
+      end
+    end
+  end
+  
+  private
+  
+  def cache_stats_response(id)
+    {
+      jsonrpc: "2.0",
+      id: id,
+      result: @metrics.stats
+    }
+  end
+end
+```
+
+## Testing Cache Behavior
+
+```ruby
+require 'minitest/autorun'
+
+class CacheTest < Minitest::Test
+  def setup
+    @cache = ThreadSafeCache.new(ttl: 1)  # 1 second TTL
+  end
+  
+  def test_cache_hit
+    call_count = 0
+    
+    # First call - cache miss
+    result1 = @cache.fetch("key") do
+      call_count += 1
+      "value"
+    end
+    
+    # Second call - cache hit
+    result2 = @cache.fetch("key") do
+      call_count += 1
+      "value"
+    end
+    
+    assert_equal "value", result1
+    assert_equal "value", result2
+    assert_equal 1, call_count  # Block only called once
+  end
+  
+  def test_cache_expiration
+    @cache.fetch("key") { "value1" }
+    
+    # Wait for expiration
+    sleep(1.1)
+    
+    # Should compute new value
+    result = @cache.fetch("key") { "value2" }
+    assert_equal "value2", result
+  end
+  
+  def test_cache_size_limit
+    cache = ThreadSafeCache.new(max_size: 3)
+    
+    # Fill cache
+    cache.fetch("key1") { "value1" }
+    cache.fetch("key2") { "value2" }
+    cache.fetch("key3") { "value3" }
+    
+    assert_equal 3, cache.size
+    
+    # Adding 4th item should trigger cleanup
+    cache.fetch("key4") { "value4" }
+    
+    assert cache.size <= 3
+  end
+end
+```
+
+## Best Practices
+
+1. **Cache appropriate data** - Not everything benefits from caching
+2. **Set reasonable TTLs** - Balance freshness with performance
+3. **Monitor cache performance** - Track hit rates and response times
+4. **Handle cache failures gracefully** - Don't let cache errors break functionality
+5. **Consider cache warming** - Pre-populate frequently accessed data
+6. **Use cache invalidation wisely** - Know when to clear stale data
+7. **Size caches appropriately** - Prevent memory issues
+8. **Use distributed caching** for multi-server deployments
+
+## Next Steps
+
+- Add [Monitoring](monitoring.md) for cache metrics
+- Implement [Rate Limiting](rate-limiting.md) with caching
+- Review [Performance](performance.md) optimization
+- Set up [Logging](logging.md) for cache debugging