tsikol 0.1.0

data/docs/guides/resources.md

@@ -0,0 +1,720 @@
+# Resources Guide
+
+Resources provide read-only data that MCP clients can access. They're perfect for exposing configuration, status information, documentation, and other data.
+
+## Table of Contents
+
+1. [What are Resources?](#what-are-resources)
+2. [Creating Resources](#creating-resources)
+3. [Resource URIs](#resource-uris)
+4. [Dynamic Resources](#dynamic-resources)
+5. [Resource Formats](#resource-formats)
+6. [Caching](#caching)
+7. [Advanced Patterns](#advanced-patterns)
+8. [Testing Resources](#testing-resources)
+
+## What are Resources?
+
+Resources are read-only data endpoints that:
+- Have unique URIs
+- Return data in various formats
+- Can be dynamic or static
+- Don't accept parameters (use URI for context)
+
+Think of resources as REST API GET endpoints.
+
+## Creating Resources
+
+### Inline Resources
+
+Simple resources defined in server.rb:
+
+```ruby
+Tsikol.server "my-server" do
+  resource "version" do
+    "1.0.0"
+  end
+  
+  resource "config/database" do
+    {
+      host: ENV['DB_HOST'] || 'localhost',
+      port: ENV['DB_PORT'] || 5432,
+      name: ENV['DB_NAME'] || 'development'
+    }.to_json
+  end
+  
+  resource "health" do
+    {
+      status: "healthy",
+      timestamp: Time.now.iso8601
+    }.to_json
+  end
+end
+```
+
+### Class-Based Resources
+
+For complex resources:
+
+```ruby
+# app/resources/system_metrics.rb
+class SystemMetrics < Tsikol::Resource
+  uri "system/metrics"
+  description "Current system metrics and statistics"
+  
+  def read
+    {
+      server: server_info,
+      system: system_info,
+      performance: performance_metrics,
+      timestamp: Time.now.iso8601
+    }.to_json
+  end
+  
+  private
+  
+  def server_info
+    {
+      name: @server.name,
+      version: Tsikol::VERSION,
+      uptime: calculate_uptime
+    }
+  end
+  
+  def system_info
+    {
+      ruby_version: RUBY_VERSION,
+      platform: RUBY_PLATFORM,
+      pid: Process.pid,
+      memory_usage: memory_usage
+    }
+  end
+  
+  def performance_metrics
+    {
+      total_requests: @server.metrics.get(:requests_total),
+      average_response_time: @server.metrics.average(:response_time),
+      error_rate: calculate_error_rate
+    }
+  end
+  
+  def calculate_uptime
+    return 0 unless @start_time
+    Time.now - @start_time
+  end
+  
+  def memory_usage
+    # Simple calculation
+    "#{(GC.stat[:heap_live_slots] * 40.0 / 1024 / 1024).round(2)}MB"
+  end
+  
+  def calculate_error_rate
+    total = @server.metrics.get(:requests_total)
+    errors = @server.metrics.get(:errors_total)
+    return 0.0 if total == 0
+    (errors.to_f / total * 100).round(2)
+  end
+  
+  def set_server(server)
+    @server = server
+    @start_time = Time.now
+  end
+end
+```
+
+## Resource URIs
+
+### URI Conventions
+
+URIs should be:
+- Descriptive and hierarchical
+- Use forward slashes for nesting
+- Lowercase with hyphens or underscores
+
+```ruby
+# Good URIs
+"config"                  # Top-level config
+"config/database"         # Database config
+"system/health"          # System health
+"api/v1/documentation"   # Versioned API docs
+
+# Avoid
+"getConfig"              # Not RESTful
+"database-config-data"   # Too flat
+"SYSTEM_HEALTH"         # Wrong case
+```
+
+### Dynamic URI Patterns
+
+For resources that represent collections:
+
+```ruby
+# app/resources/user_profile.rb
+class UserProfile < Tsikol::Resource
+  uri "users/current/profile"
+  description "Current user's profile"
+  
+  def read
+    # In real app, get current user from context
+    {
+      id: 1,
+      name: "Current User",
+      preferences: load_preferences
+    }.to_json
+  end
+end
+
+# app/resources/project_readme.rb
+class ProjectReadme < Tsikol::Resource
+  uri "project/readme"
+  description "Project README file"
+  
+  def read
+    if File.exist?("README.md")
+      File.read("README.md")
+    else
+      "No README found"
+    end
+  end
+end
+```
+
+## Dynamic Resources
+
+### Real-Time Data
+
+```ruby
+class LiveMetrics < Tsikol::Resource
+  uri "metrics/live"
+  description "Real-time metrics"
+  
+  def read
+    {
+      timestamp: Time.now.iso8601,
+      requests_per_second: calculate_rps,
+      active_connections: active_connections,
+      queue_depth: queue_depth,
+      cpu_usage: cpu_usage,
+      memory_usage: memory_usage
+    }.to_json
+  end
+  
+  private
+  
+  def calculate_rps
+    # Calculate requests in last second
+    recent = @server.metrics.recent_requests(1)
+    recent.count
+  end
+  
+  def active_connections
+    Thread.list.select(&:alive?).count
+  end
+  
+  def queue_depth
+    # Implementation specific
+    0
+  end
+  
+  def cpu_usage
+    # Platform specific implementation
+    "#{rand(0..100)}%"
+  end
+end
+```
+
+### Database-Backed Resources
+
+```ruby
+class DatabaseSchema < Tsikol::Resource
+  uri "database/schema"
+  description "Current database schema"
+  
+  def read
+    tables = fetch_tables
+    schema = tables.map do |table|
+      {
+        name: table,
+        columns: fetch_columns(table),
+        indexes: fetch_indexes(table)
+      }
+    end
+    
+    {
+      database: database_name,
+      tables: schema,
+      generated_at: Time.now.iso8601
+    }.to_json
+  end
+  
+  private
+  
+  def fetch_tables
+    # Database specific
+    ["users", "posts", "comments"]
+  end
+  
+  def fetch_columns(table)
+    # Database specific
+    case table
+    when "users"
+      ["id", "email", "name", "created_at"]
+    when "posts"
+      ["id", "user_id", "title", "content", "published_at"]
+    else
+      ["id", "created_at", "updated_at"]
+    end
+  end
+  
+  def fetch_indexes(table)
+    # Database specific
+    ["#{table}_pkey"]
+  end
+  
+  def database_name
+    ENV['DATABASE_NAME'] || 'development'
+  end
+end
+```
+
+## Resource Formats
+
+### JSON Resources
+
+Most common format:
+
+```ruby
+class ApiEndpoints < Tsikol::Resource
+  uri "api/endpoints"
+  description "Available API endpoints"
+  
+  def read
+    {
+      version: "1.0",
+      endpoints: [
+        {
+          path: "/users",
+          methods: ["GET", "POST"],
+          description: "User management"
+        },
+        {
+          path: "/users/:id",
+          methods: ["GET", "PUT", "DELETE"],
+          description: "Individual user operations"
+        }
+      ]
+    }.to_json
+  end
+end
+```
+
+### Text Resources
+
+Plain text or markdown:
+
+```ruby
+class Changelog < Tsikol::Resource
+  uri "changelog"
+  description "Project changelog"
+  
+  def read
+    if File.exist?("CHANGELOG.md")
+      File.read("CHANGELOG.md")
+    else
+      "No changelog available"
+    end
+  end
+end
+```
+
+### CSV Resources
+
+Tabular data:
+
+```ruby
+class UserReport < Tsikol::Resource
+  uri "reports/users.csv"
+  description "User report in CSV format"
+  
+  def read
+    require 'csv'
+    
+    CSV.generate do |csv|
+      csv << ["ID", "Name", "Email", "Created"]
+      
+      users.each do |user|
+        csv << [user[:id], user[:name], user[:email], user[:created_at]]
+      end
+    end
+  end
+  
+  private
+  
+  def users
+    # Fetch from database
+    [
+      { id: 1, name: "Alice", email: "alice@example.com", created_at: "2024-01-01" },
+      { id: 2, name: "Bob", email: "bob@example.com", created_at: "2024-01-02" }
+    ]
+  end
+end
+```
+
+### Binary Resources
+
+Base64 encoded:
+
+```ruby
+class Logo < Tsikol::Resource
+  uri "assets/logo"
+  description "Company logo"
+  
+  def read
+    if File.exist?("logo.png")
+      content = File.read("logo.png", mode: "rb")
+      {
+        mime_type: "image/png",
+        encoding: "base64",
+        data: Base64.encode64(content)
+      }.to_json
+    else
+      { error: "Logo not found" }.to_json
+    end
+  end
+end
+```
+
+## Caching
+
+### Simple Caching
+
+```ruby
+class CachedResource < Tsikol::Resource
+  uri "expensive/data"
+  description "Expensive computation (cached)"
+  
+  def initialize
+    super
+    @cache = nil
+    @cache_time = nil
+    @cache_ttl = 300 # 5 minutes
+  end
+  
+  def read
+    if cache_valid?
+      log :debug, "Cache hit"
+      @cache
+    else
+      log :debug, "Cache miss, computing..."
+      @cache = compute_expensive_data
+      @cache_time = Time.now
+      @cache
+    end
+  end
+  
+  private
+  
+  def cache_valid?
+    return false unless @cache && @cache_time
+    Time.now - @cache_time < @cache_ttl
+  end
+  
+  def compute_expensive_data
+    # Simulate expensive operation
+    sleep(0.1)
+    {
+      result: "Expensive data",
+      computed_at: Time.now.iso8601
+    }.to_json
+  end
+end
+```
+
+### Conditional Caching
+
+```ruby
+class ConditionalCache < Tsikol::Resource
+  uri "data/conditional"
+  description "Conditionally cached data"
+  
+  def read
+    data = fetch_data
+    
+    # Cache based on data characteristics
+    if should_cache?(data)
+      @cached_data = data
+      @cache_key = generate_cache_key(data)
+    end
+    
+    format_response(data)
+  end
+  
+  private
+  
+  def should_cache?(data)
+    # Cache if data is large or expensive
+    data.size > 1000 || data[:expensive]
+  end
+  
+  def generate_cache_key(data)
+    Digest::SHA256.hexdigest(data.to_s)
+  end
+end
+```
+
+## Advanced Patterns
+
+### Aggregated Resources
+
+Combine multiple data sources:
+
+```ruby
+class Dashboard < Tsikol::Resource
+  uri "dashboard"
+  description "Aggregated dashboard data"
+  
+  def read
+    {
+      summary: fetch_summary,
+      metrics: fetch_metrics,
+      recent_activity: fetch_recent_activity,
+      alerts: fetch_alerts
+    }.to_json
+  end
+  
+  private
+  
+  def fetch_summary
+    {
+      total_users: count_users,
+      active_sessions: count_sessions,
+      revenue_today: calculate_revenue
+    }
+  end
+  
+  def fetch_metrics
+    SystemMetrics.new.read
+  end
+  
+  def fetch_recent_activity
+    # Last 10 activities
+    []
+  end
+  
+  def fetch_alerts
+    # Active alerts
+    []
+  end
+end
+```
+
+### Filtered Resources
+
+Resources with virtual filters:
+
+```ruby
+class FilteredLogs < Tsikol::Resource
+  uri "logs/recent"
+  description "Recent log entries"
+  
+  def read
+    # In real app, URI could indicate filter
+    # e.g., "logs/error" for error logs only
+    
+    logs = if uri.include?("error")
+      fetch_error_logs
+    elsif uri.include?("warning")
+      fetch_warning_logs
+    else
+      fetch_all_logs
+    end
+    
+    format_logs(logs)
+  end
+  
+  private
+  
+  def fetch_error_logs
+    read_log_file.select { |line| line.include?("[ERROR]") }
+  end
+  
+  def fetch_warning_logs
+    read_log_file.select { |line| line.include?("[WARNING]") }
+  end
+  
+  def fetch_all_logs
+    read_log_file.last(100)
+  end
+  
+  def read_log_file
+    File.readlines("app.log") rescue []
+  end
+  
+  def format_logs(logs)
+    {
+      count: logs.size,
+      entries: logs.map { |log| parse_log_entry(log) }
+    }.to_json
+  end
+end
+```
+
+### Streaming Resources
+
+For large data sets:
+
+```ruby
+class LargeDataset < Tsikol::Resource
+  uri "data/large"
+  description "Large dataset (streamed)"
+  
+  def read
+    # Return metadata about the dataset
+    {
+      total_records: count_records,
+      chunk_size: 1000,
+      chunks_available: calculate_chunks,
+      access_pattern: "Use data/large/chunk/{n} to access chunks"
+    }.to_json
+  end
+  
+  private
+  
+  def count_records
+    # Implementation
+    1_000_000
+  end
+  
+  def calculate_chunks
+    (count_records / 1000.0).ceil
+  end
+end
+
+# Separate resource for chunks
+class DataChunk < Tsikol::Resource
+  uri "data/large/chunk"  # Would need custom routing
+  description "Data chunk"
+  
+  def read
+    chunk_number = extract_chunk_number
+    offset = chunk_number * 1000
+    
+    records = fetch_records(offset, 1000)
+    
+    {
+      chunk: chunk_number,
+      records: records,
+      has_more: has_more_records?(offset + 1000)
+    }.to_json
+  end
+end
+```
+
+## Testing Resources
+
+### Basic Resource Test
+
+```ruby
+require 'minitest/autorun'
+require 'tsikol/test_helpers'
+
+class SystemMetricsTest < Minitest::Test
+  include Tsikol::TestHelpers::Assertions
+  
+  def setup
+    @server = Tsikol::Server.new(name: "test")
+    @server.register_resource_instance(SystemMetrics.new)
+    @client = Tsikol::TestHelpers::TestClient.new(@server)
+    @client.initialize_connection
+  end
+  
+  def test_read_metrics
+    response = @client.read_resource("system/metrics")
+    assert_successful_response(response)
+    
+    content = response.dig(:result, :contents, 0, :text)
+    data = JSON.parse(content)
+    
+    assert data["server"]
+    assert data["system"]
+    assert data["performance"]
+    assert data["timestamp"]
+  end
+  
+  def test_metrics_structure
+    response = @client.read_resource("system/metrics")
+    content = response.dig(:result, :contents, 0, :text)
+    data = JSON.parse(content)
+    
+    # Check server info
+    assert_equal "test", data["server"]["name"]
+    assert data["server"]["uptime"] >= 0
+    
+    # Check system info
+    assert_equal RUBY_VERSION, data["system"]["ruby_version"]
+    assert data["system"]["memory_usage"]
+  end
+end
+```
+
+### Testing Dynamic Resources
+
+```ruby
+class LiveMetricsTest < Minitest::Test
+  def test_real_time_data_changes
+    response1 = @client.read_resource("metrics/live")
+    sleep(0.1)
+    response2 = @client.read_resource("metrics/live")
+    
+    data1 = JSON.parse(response1.dig(:result, :contents, 0, :text))
+    data2 = JSON.parse(response2.dig(:result, :contents, 0, :text))
+    
+    # Timestamps should be different
+    refute_equal data1["timestamp"], data2["timestamp"]
+  end
+end
+```
+
+### Testing Cached Resources
+
+```ruby
+class CachedResourceTest < Minitest::Test
+  def test_caching_behavior
+    # First call should compute
+    start = Time.now
+    response1 = @client.read_resource("expensive/data")
+    duration1 = Time.now - start
+    
+    # Second call should be cached
+    start = Time.now
+    response2 = @client.read_resource("expensive/data")
+    duration2 = Time.now - start
+    
+    # Cached call should be much faster
+    assert duration2 < duration1 / 10
+    
+    # Content should be identical
+    assert_equal(
+      response1.dig(:result, :contents, 0, :text),
+      response2.dig(:result, :contents, 0, :text)
+    )
+  end
+end
+```
+
+## Best Practices
+
+1. **Use Clear URIs**: Make them intuitive and hierarchical
+2. **Return Consistent Formats**: Usually JSON for structured data
+3. **Include Metadata**: Timestamps, versions, etc.
+4. **Handle Errors Gracefully**: Return error info in response
+5. **Cache When Appropriate**: For expensive operations
+6. **Keep Resources Read-Only**: Use tools for modifications
+7. **Document Format**: Describe what the resource returns
+
+## Next Steps
+
+- Learn about [Prompts](prompts.md)
+- Explore [Testing](testing.md)
+- Add [Caching](../cookbook/caching.md)
+- Implement [Monitoring](../cookbook/monitoring.md)